original/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 .\" 2008-11-12, mtk, removed CPU_*() macro descriptions to a
  33 .\" separate CPU_SET(3) page.
  34 .\"
  35 .TH SCHED_SETAFFINITY 2 2010-11-06 "Linux" "Linux Programmer's Manual"
  36 .SH NAME
  37 sched_setaffinity, sched_getaffinity \- \
  38 set and get a process's CPU affinity mask
  39 .SH SYNOPSIS
  40 .nf
  41 .BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
  42 .B #include <sched.h>
  43 .sp
  44 .BI "int sched_setaffinity(pid_t " pid ", size_t " cpusetsize ,
  45 .BI "                      cpu_set_t *" mask );
  46 .sp
  47 .BI "int sched_getaffinity(pid_t " pid ", size_t " cpusetsize ,
  48 .BI "                      cpu_set_t *" mask );
  49 .fi
  50 .SH DESCRIPTION
  51 A process's CPU affinity mask determines the set of CPUs on which
  52 it is eligible to run.
  53 On a multiprocessor system, setting the CPU affinity mask
  54 can be used to obtain performance benefits.
  55 For example,
  56 by dedicating one CPU to a particular process
  57 (i.e., setting the affinity mask of that process to specify a single CPU,
  58 and setting the affinity mask of all other processes to exclude that CPU),
  59 it is possible to ensure maximum execution speed for that process.
  60 Restricting a process to run on a single CPU also avoids
  61 the performance cost caused by the cache invalidation that occurs
  62 when a process ceases to execute on one CPU and then
  63 recommences execution on a different CPU.
  64
  65 A CPU affinity mask is represented by the
  66 .I cpu_set_t
  67 structure, a "CPU set", pointed to by
  68 .IR mask .
  69 A set of macros for manipulating CPU sets is described in
  70 .BR CPU_SET (3).
  71
  72 .BR sched_setaffinity ()
  73 sets the CPU affinity mask of the process whose ID is
  74 .I pid
  75 to the value specified by
  76 .IR mask .
  77 If
  78 .I pid
  79 is zero, then the calling process is used.
  80 The argument
  81 .I cpusetsize
  82 is the length (in bytes) of the data pointed to by
  83 .IR mask .
  84 Normally this argument would be specified as
  85 .IR "sizeof(cpu_set_t)" .
  86
  87 If the process specified by
  88 .I pid
  89 is not currently running on one of the CPUs specified in
  90 .IR mask ,
  91 then that process is migrated to one of the CPUs specified in
  92 .IR mask .
  93
  94 .BR sched_getaffinity ()
  95 writes the affinity mask of the process whose ID is
  96 .I pid
  97 into the
  98 .I cpu_set_t
  99 structure pointed to by
 100 .IR mask .
 101 The
 102 .I cpusetsize
 103 argument specifies the size (in bytes) of
 104 .IR mask .
 105 If
 106 .I pid
 107 is zero, then the mask of the calling process is returned.
 108 .SH "RETURN VALUE"
 109 On success,
 110 .BR sched_setaffinity ()
 111 and
 112 .BR sched_getaffinity ()
 113 return 0.
 114 On error, \-1 is returned, and
 115 .I errno
 116 is set appropriately.
 117 .SH ERRORS
 118 .TP
 119 .B EFAULT
 120 A supplied memory address was invalid.
 121 .TP
 122 .B EINVAL
 123 The affinity bit mask
 124 .I mask
 125 contains no processors that are currently physically on the system
 126 and permitted to the process according to any restrictions that
 127 may be imposed by the "cpuset" mechanism described in
 128 .BR cpuset (7).
 129 .TP
 130 .B EINVAL
 131 .RB ( sched_getaffinity ()
 132 and, in kernels before 2.6.9,
 133 .BR sched_setaffinity ())
 134 .I cpusetsize
 135 is smaller than the size of the affinity mask used by the kernel.
 136 .TP
 137 .B EPERM
 138 .RB ( sched_setaffinity ())
 139 The calling process does not have appropriate privileges.
 140 The caller needs an effective user ID equal to the real user ID
 141 or effective user ID of the process identified by
 142 .IR pid ,
 143 or it must possess the
 144 .B CAP_SYS_NICE
 145 capability.
 146 .TP
 147 .B ESRCH
 148 The process whose ID is \fIpid\fP could not be found.
 149 .SH VERSIONS
 150 The CPU affinity system calls were introduced in Linux kernel 2.5.8.
 151 The system call wrappers were introduced in glibc 2.3.
 152 Initially, the glibc interfaces included a
 153 .I cpusetsize
 154 argument, typed as
 155 .IR "unsigned int" .
 156 In glibc 2.3.3, the
 157 .I cpusetsize
 158 argument was removed, but was then restored in glibc 2.3.4, with type
 159 .IR size_t .
 160 .SH "CONFORMING TO"
 161 These system calls are Linux-specific.
 162 .SH "NOTES"
 163 After a call to
 164 .BR sched_setaffinity (),
 165 the set of CPUs on which the process will actually run is
 166 the intersection of the set specified in the
 167 .I mask
 168 argument and the set of CPUs actually present on the system.
 169 The system may further restrict the set of CPUs on which the process
 170 runs if the "cpuset" mechanism described in
 171 .BR cpuset (7)
 172 is being used.
 173 These restrictions on the actual set of CPUs on which the process
 174 will run are silently imposed by the kernel.
 175
 176 .BR sched_setscheduler (2)
 177 has a description of the Linux scheduling scheme.
 178 .PP
 179 The affinity mask is actually a per-thread attribute that can be
 180 adjusted independently for each of the threads in a thread group.
 181 The value returned from a call to
 182 .BR gettid (2)
 183 can be passed in the argument
 184 .IR pid .
 185 Specifying
 186 .I pid
 187 as 0 will set the attribute for the calling thread,
 188 and passing the value returned from a call to
 189 .BR getpid (2)
 190 will set the attribute for the main thread of the thread group.
 191 (If you are using the POSIX threads API, then use
 192 .BR pthread_setaffinity_np (3)
 193 instead of
 194 .BR sched_setaffinity ().)
 195
 196 A child created via
 197 .BR fork (2)
 198 inherits its parent's CPU affinity mask.
 199 The affinity mask is preserved across an
 200 .BR execve (2).
 201
 202 This manual page describes the glibc interface for the CPU affinity calls.
 203 The actual system call interface is slightly different, with the
 204 .I mask
 205 being typed as
 206 .IR "unsigned long *" ,
 207 reflecting the fact that the underlying implementation of CPU
 208 sets is a simple bit mask.
 209 On success, the raw
 210 .BR sched_getaffinity ()
 211 system call returns the size (in bytes) of the
 212 .I cpumask_t
 213 data type that is used internally by the kernel to
 214 represent the CPU set bit mask.
 215 .SH "SEE ALSO"
 216 .BR clone (2),
 217 .BR getcpu (2),
 218 .BR getpriority (2),
 219 .BR gettid (2),
 220 .BR nice (2),
 221 .BR sched_get_priority_max (2),
 222 .BR sched_get_priority_min (2),
 223 .BR sched_getscheduler (2),
 224 .BR sched_setscheduler (2),
 225 .BR setpriority (2),
 226 .BR CPU_SET (3),
 227 .BR pthread_setaffinity_np (3),
 228 .BR sched_getcpu (3),
 229 .BR capabilities (7),
 230 .BR cpuset (7)