man2/sched_setaffinity.2

   1 .\" man2/sched_setaffinity.2 - sched_setaffinity and sched_getaffinity man page
   2 .\"
   3 .\" Copyright (C) 2002 Robert Love
   4 .\" and Copyright (C) 2006 Michael Kerrisk
   5 .\"
   6 .\" This is free documentation; you can redistribute it and/or
   7 .\" modify it under the terms of the GNU General Public License as
   8 .\" published by the Free Software Foundation; either version 2 of
   9 .\" the License, or (at your option) any later version.
  10 .\"
  11 .\" The GNU General Public License's references to "object code"
  12 .\" and "executables" are to be interpreted as the output of any
  13 .\" document formatting or typesetting system, including
  14 .\" intermediate and printed output.
  15 .\"
  16 .\" This manual is distributed in the hope that it will be useful,
  17 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 .\" GNU General Public License for more details.
  20 .\"
  21 .\" You should have received a copy of the GNU General Public
  22 .\" License along with this manual; if not, write to the Free
  23 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  24 .\" USA.
  25 .\"
  26 .\" 2002-11-19 Robert Love <rml@tech9.net> - initial version
  27 .\" 2004-04-20 mtk - fixed description of return value
  28 .\" 2004-04-22 aeb - added glibc prototype history
  29 .\" 2005-05-03 mtk - noted that sched_setaffinity may cause thread
  30 .\"     migration and that CPU affinity is a per-thread attribute.
  31 .\" 2006-02-03 mtk -- Major rewrite
  32 .\"
  33 .TH SCHED_SETAFFINITY 2 2006-02-03 "Linux" "Linux Programmer's Manual"
  34 .SH NAME
  35 sched_setaffinity, sched_getaffinity, CPU_CLR, CPU_ISSET, CPU_SET, CPU_ZERO \
  36 \- set and get a process's CPU affinity mask
  37 .SH SYNOPSIS
  38 .nf
  39 .B #define _GNU_SOURCE
  40 .B #include <sched.h>
  41 .sp
  42 .BI "int sched_setaffinity(pid_t " pid ", unsigned int " cpusetsize ,
  43 .BI "                      cpu_set_t *" mask );
  44 .sp
  45 .BI "int sched_getaffinity(pid_t " pid ", unsigned int " cpusetsize ,
  46 .BI "                      cpu_set_t *" mask );
  47 .sp
  48 .BI "void CPU_CLR(int " cpu ", cpu_set_t *" set );
  49 .br
  50 .BI "int CPU_ISSET(int " cpu ", cpu_set_t *" set );
  51 .br
  52 .BI "void CPU_SET(int " cpu ", cpu_set_t *" set );
  53 .br
  54 .BI "void CPU_ZERO(cpu_set_t *" set );
  55 .fi
  56 .SH DESCRIPTION
  57 A process's CPU affinity mask determines the set of CPUs on which
  58 it is eligible to run.
  59 On a multiprocessor system, setting the CPU affinity mask
  60 can be used to obtain performance benefits.
  61 For example,
  62 by dedicating one CPU to a particular process
  63 (i.e., setting the affinity mask of that process to specify a single CPU,
  64 and setting the affinity mask of all other processes to exclude that CPU),
  65 it is possible to ensure maximum execution speed for that process.
  66 Restricting a process to run on a single CPU also prevents
  67 the performance cost caused by the cache invalidation that occurs
  68 when a process ceases to execute on one CPU and then
  69 recommences execution on a different CPU.
  70
  71 A CPU affinity mask is represented by the
  72 .I cpu_set_t
  73 structure, a "CPU set", pointed to by
  74 .IR mask .
  75 Four macros are provided to manipulate CPU sets.
  76 .BR CPU_ZERO ()
  77 clears a set.
  78 .BR CPU_SET ()
  79 and
  80 .BR CPU_CLR ()
  81 respectively add and remove a given CPU from a set.
  82 .BR CPU_ISSET ()
  83 tests to see if a CPU is part of the set; this is useful after
  84 .BR sched_getaffinity ()
  85 returns.
  86 The first available CPU on the system corresponds to a
  87 .I cpu
  88 value of 0, the next CPU corresponds to a
  89 .I cpu
  90 value of 1, and so on.
  91 The constant
  92 .B CPU_SETSIZE
  93 (1024) specifies a value one greater than the maximum CPU
  94 number that can be stored in a CPU set.
  95
  96 .BR sched_setaffinity ()
  97 sets the CPU affinity mask of the process whose ID is
  98 .IR pid
  99 to the value specified by
 100 .IR mask .
 101 If
 102 .I pid
 103 is zero, then the calling process is used.
 104 The argument
 105 .I cpusetsize
 106 is the length (in bytes) of the data pointed to by
 107 .IR mask .
 108 Normally this argument would be specified as
 109 .IR "sizeof(cpu_set_t)" .
 110
 111 If the process specified by
 112 .I pid
 113 is not currently running on one of the CPUs specified in
 114 .IR mask ,
 115 then that process is migrated to one of the CPUs specified in
 116 .IR mask .
 117
 118 .BR sched_getaffinity ()
 119 writes the affinity mask of the process whose ID is
 120 .IR pid
 121 into the
 122 .I cpu_set_t
 123 structure pointed to by
 124 .IR mask .
 125 The
 126 .I cpusetsize
 127 argument specifies the size (in bytes) of
 128 .IR mask .
 129 If
 130 .I pid
 131 is zero, then the mask of the calling process is returned.
 132 .SH "RETURN VALUE"
 133 On success,
 134 .BR sched_setaffinity ()
 135 and
 136 .BR sched_getaffinity ()
 137 return 0.
 138 On error, \-1 is returned, and
 139 .I errno
 140 is set appropriately.
 141 .SH ERRORS
 142 .TP
 143 .B EFAULT
 144 A supplied memory address was invalid.
 145 .TP
 146 .B EINVAL
 147 The affinity bit mask
 148 .I mask
 149 contains no processors that are physically on the system,
 150 .\" The following can only (?) occur with the raw sched_getaffinity()
 151 .\" system call (MTK, 3 Feb 2006):
 152 or
 153 .I cpusetsize
 154 is smaller than the size of the affinity mask used by the kernel.
 155 .TP
 156 .B EPERM
 157 The calling process does not have appropriate privileges.
 158 The process calling
 159 .BR sched_setaffinity ()
 160 needs an effective user ID equal to the user ID or effective user ID
 161 of the process identified by
 162 .IR pid ,
 163 or it must possess the
 164 .BR CAP_SYS_NICE
 165 capability.
 166 .TP
 167 .B ESRCH
 168 The process whose ID is \fIpid\fP could not be found.
 169 .SH VERSIONS
 170 The CPU affinity system calls were introduced in Linux kernel 2.5.8.
 171 The library interfaces were introduced in glibc 2.3.
 172 Initially, the glibc interfaces included a
 173 .I cpusetsize
 174 argument.
 175 In glibc 2.3.3, the
 176 .I cpusetsize
 177 argument was removed, but this argument was restored in glibc 2.3.4.
 178 .fi
 179 .SH "CONFORMING TO"
 180 These system calls are Linux specific.
 181 .SH "NOTES"
 182 The affinity mask is actually a per-thread attribute that can be
 183 adjusted independently for each of the threads in a thread group.
 184 The value returned from a call to
 185 .BR gettid (2)
 186 can be passed in the argument
 187 .IR pid .
 188 Specifying
 189 .I pid
 190 as 0 will set the attribute for the current thread,
 191 and passing the value returned from a call to
 192 .BR getpid (2)
 193 will set the attribute for the main thread of the thread group.
 194
 195 A child created via
 196 .BR fork (2)
 197 inherits its parent's CPU affinity mask.
 198 The affinity mask is preserved across an
 199 .BR execve (2).
 200
 201 This manual page describes the glibc interface for the CPU affinity calls.
 202 The actual system call interface is slightly different, with the
 203 .I mask
 204 being typed as
 205 .IR "unsigned long *" ,
 206 reflecting that the fact that the underlying implementation of CPU
 207 sets is a simple bit mask.
 208 On success, the raw
 209 .BR sched_getaffinity ()
 210 system call returns the size (in bytes) of the
 211 .I cpumask_t
 212 data type that is used internally by the kernel to
 213 represent the CPU set bit mask.
 214 .SH "SEE ALSO"
 215 .BR clone (2),
 216 .BR getpriority (2),
 217 .BR gettid (2),
 218 .BR nice (2),
 219 .BR sched_get_priority_max (2),
 220 .BR sched_get_priority_min (2),
 221 .BR sched_getscheduler (2),
 222 .BR sched_setscheduler (2),
 223 .BR setpriority (2),
 224 .BR capabilities (7)
 225 .PP
 226 .BR sched_setscheduler (2)
 227 has a description of the Linux scheduling scheme.