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 #include <sched.h>
  40 .sp
  41 .BI "int sched_setaffinity(pid_t " pid ", unsigned int " cpusetsize ,
  42 .BI "                      cpu_set_t *" mask );
  43 .sp
  44 .BI "int sched_getaffinity(pid_t " pid ", unsigned int " cpusetsize ,
  45 .BI "                      cpu_set_t *" mask );
  46 .sp
  47 .BI "void CPU_CLR(int " cpu ", cpu_set_t *" set );
  48 .br
  49 .BI "int CPU_ISSET(int " cpu ", cpu_set_t *" set );
  50 .br
  51 .BI "void CPU_SET(int " cpu ", cpu_set_t *" set );
  52 .br
  53 .BI "void CPU_ZERO(cpu_set_t *" set );
  54 .fi
  55 .SH DESCRIPTION
  56 A process's CPU affinity mask determines the set of CPUs on which
  57 it is eligible to run.
  58 On a multiprocessor system, setting the CPU affinity mask
  59 can be used to obtain performance benefits.
  60 For example,
  61 by dedicating one CPU to a particular process
  62 (i.e., setting the affinity mask of that process to specify a single CPU,
  63 and setting the affinity mask of all other processes to exclude that CPU),
  64 it is possible to ensure maximum execution speed for that process.
  65 Restricting a process to run on a single CPU also prevents
  66 the performance cost caused by the cache invalidation that occurs
  67 when a process ceases to execute on one CPU and then
  68 recommences execution on a different CPU.
  69
  70 A CPU affinity mask is represented by the
  71 .I cpu_set_t
  72 structure, a "CPU set", pointed to by
  73 .IR mask .
  74 Four macros are provided to manipulate CPU sets.
  75 .BR CPU_ZERO ()
  76 clears a set.
  77 .BR CPU_SET ()
  78 and
  79 .BR CPU_CLR ()
  80 respectively add and remove a given CPU from a set.
  81 .BR CPU_ISSET ()
  82 tests to see if a CPU is part of the set; this is useful after
  83 .BR sched_getaffinity ()
  84 returns.
  85 The first available CPU on the system corresponds to a
  86 .I cpu
  87 value of 0, the next CPU corresponds to a
  88 .I cpu
  89 value of 1, and so on.
  90 The constant
  91 .B CPU_SETSIZE
  92 (1024) specifies a value one greater than the maximum CPU
  93 number that can be stored in a CPU set.
  94
  95 .BR sched_setaffinity ()
  96 sets the CPU affinity mask of the process whose ID is
  97 .IR pid
  98 to the value specified by
  99 .IR mask .
 100 If
 101 .I pid
 102 is zero, then the calling process is used.
 103 The argument
 104 .I cpusetsize
 105 is the length (in bytes) of the data pointed to by
 106 .IR mask .
 107 Normally this argument would be specified as
 108 .IR "sizeof(cpu_set_t)" .
 109
 110 If the process specified by
 111 .I pid
 112 is not currently running on one of the CPUs specified in
 113 .IR mask ,
 114 then that process is migrated to one of the CPUs specified in
 115 .IR mask .
 116
 117 .BR sched_getaffinity ()
 118 writes the affinity mask of the process whose ID is
 119 .IR pid
 120 into the
 121 .I cpu_set_t
 122 structure pointed to by
 123 .IR mask .
 124 The
 125 .I cpusetsize
 126 argument specifies the size (in bytes) of
 127 .IR mask .
 128 If
 129 .I pid
 130 is zero, then the mask of the calling process is returned.
 131 .SH "RETURN VALUE"
 132 On success,
 133 .BR sched_setaffinity ()
 134 and
 135 .BR sched_getaffinity ()
 136 return 0.
 137 On error, \-1 is returned, and
 138 .I errno
 139 is set appropriately.
 140 .SH ERRORS
 141 .TP
 142 .B EFAULT
 143 A supplied memory address was invalid.
 144 .TP
 145 .B EINVAL
 146 The affinity bitmask
 147 .I mask
 148 contains no processors that are physically on the system,
 149 .\" The following can only (?) occur with the raw sched_getaffinity()
 150 .\" system call (MTK, 3 Feb 2006):
 151 or
 152 .I cpusetsize
 153 is smaller than the size of the affinity mask used by the kernel.
 154 .TP
 155 .B EPERM
 156 The calling process does not have appropriate privileges.
 157 The process calling
 158 .BR sched_setaffinity ()
 159 needs an effective user ID equal to the user ID or effective user ID
 160 of the process identified by
 161 .IR pid ,
 162 or it must possess the
 163 .IR CAP_SYS_NICE
 164 capability.
 165 .TP
 166 .B ESRCH
 167 The process whose ID is \fIpid\fR could not be found.
 168 .SH "CONFORMING TO"
 169 These system calls are Linux specific.
 170 .SH "NOTES"
 171 The affinity mask is actually a per-thread attribute that can be
 172 adjusted independently for each of the threads in a thread group.
 173 The value returned from a call to
 174 .BR gettid (2)
 175 can be passed in the argument
 176 .IR pid .
 177
 178 A child created via
 179 .BR fork (2)
 180 inherits its parent's CPU affinity mask.
 181 The affinity mask is preserved across an
 182 .BR execve (2).
 183
 184 This manual page describes the glibc interface for the CPU affinity calls.
 185 The actual system call interface is slightly different, with the
 186 .I mask
 187 being typed as
 188 .IR "unsigned long *" ,
 189 reflecting that the fact that the underlying implementation of CPU
 190 sets is a simple bitmask.
 191 On success, the raw
 192 .BR sched_getaffinity ()
 193 system call returns the size (in bytes) of the
 194 .I cpumask_t
 195 data type that is used internally by the kernel to
 196 represent the CPU set bitmask.
 197 .SH "HISTORY"
 198 The CPU affinity system calls were introduced in Linux kernel 2.5.8.
 199 The library interfaces were introduced in glibc 2.3.
 200 Initially, the glibc interfaces included a
 201 .I cpusetsize
 202 argument.
 203 In glibc 2.3.3, the
 204 .I cpusetsize
 205 argument was removed, but this argument was restored in glibc 2.3.4.
 206 .fi
 207 .SH "SEE ALSO"
 208 .BR clone (2),
 209 .BR getpriority (2),
 210 .BR gettid (2),
 211 .BR nice (2),
 212 .BR sched_get_priority_max (2),
 213 .BR sched_get_priority_min (2),
 214 .BR sched_getscheduler (2),
 215 .BR sched_setscheduler (2),
 216 .BR setpriority (2),
 217 .BR capabilities (7)
 218 .PP
 219 .BR sched_setscheduler (2)
 220 has a description of the Linux scheduling scheme.