man-pages/man2/sched_setaffinity.2

.\" man2/sched_setaffinity.2 - sched_setaffinity and sched_getaffinity man page
.\"
.\" Copyright (C) 2002 Robert Love
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
.\" USA.
.\"
.\" 2002-11-19 Robert Love <rml@tech9.net> - initial version
.\" 2004-04-20 mtk - fixed description of return value
.\" 2004-04-22 aeb - added glibc prototype history
.\" 2005-05-03 mtk - noted that sched_setaffinity may cause thread 
.\"	migration and that CPU affinity is a per-thread attribute.
.\"
.TH SCHED_SETAFFINITY 2 2005-05-03 "Linux" "Linux Programmer's Manual"
.SH NAME
sched_setaffinity, sched_getaffinity \- set and get a process's CPU
affinity mask
.SH SYNOPSIS
.B #include <sched.h>
.sp
.BI "int sched_setaffinity(pid_t " pid ", unsigned int " len ,
.BI "cpu_set_t *" mask );
.sp
.BI "int sched_getaffinity(pid_t " pid ", unsigned int " len ,
.BI "cpu_set_t *" mask );
.sp
.BI "CPU_CLR(int " cpu ", cpu_set_t *" set );
.br
.BI "CPU_ISSET(int " cpu ", cpu_set_t *" set );
.br
.BI "CPU_SET(int " cpu ", cpu_set_t *" set );
.br
.BI "CPU_ZERO(cpu_set_t *" set );
.SH DESCRIPTION
.BR sched_setaffinity ()
sets the CPU affinity mask of the process denoted by
.IR pid .
If
.I pid
is zero, then the current process is used.
.sp
The affinity mask is represented by the 
.I cpu_set_t 
value pointed to by
.IR mask .

The least significant bit corresponds to the first logical processor
number on the system, while the most significant bit corresponds to
the last logical processor number on the system.
A set bit corresponds to a legally schedulable CPU while an unset
bit corresponds to an illegally schedulable CPU.
In other words, a process is bound to and will only run on
processors whose corresponding bit is set.
Usually, all bits in the mask are set.
.sp
If the process specified by
.I pid
is not curently running on one of the CPUs specified in
.IR mask ,
then that process is migrated to one of the CPUs specified in
.IR mask .
.sp
The argument
.I len
is the length (in bytes) of the data pointed to by
.IR mask .
Normally this is the size of a word on the system.  For compatibility with
future versions of the Linux kernel, since this size can change, the bitmask
supplied must be at least as large as the affinity mask stored in the kernel.
.sp
The function
.BR sched_getaffinity ()
writes into the pointer supplied by
.I mask
that has size
.I len
the affinity mask of process
.IR pid .
If
.I pid
is zero, then the mask of the current process is returned.

.SH "RETURN VALUE"
On success,
.BR sched_setaffinity ()
returns 0.
On error, \-1 is returned, and
.I errno
is set appropriately.

On success,
.BR sched_getaffinity ()
always returns the size (in bytes) of the affinity mask used by the kernel.
On error, \-1 is returned, and
.I errno
is set appropriately.

.SH ERRORS
.TP
.B EFAULT
A supplied memory address was invalid.
.TP
.B EINVAL
The affinity bitmask
.I mask
contains no processors that are physically on the system, or the length
.I len
is smaller than the size of the affinity mask used by the kernel.
.TP
.B EPERM
The calling process does not have appropriate privileges.
The process calling
.BR sched_setaffinity ()
needs an effective user ID equal to the user ID or effective user ID
of the process identified by
.IR pid ,
or it must possess the
.IR CAP_SYS_NICE
capability.
.TP
.B ESRCH
The process whose ID is \fIpid\fR could not be found.
.SH "NOTES"
The affinity mask is actually a per-thread attribute that can be
adjusted independently for each of the threads in a thread group.
The value returned from a call to
.BR gettid (2)
can be passed in the argument
.IR pid .
.SH "HISTORY"
The affinity syscalls were introduced in Linux kernel 2.5.8.
The library calls were introduced in glibc 2.3, and are still in
glibc 2.3.2. Later glibc 2.3.2 development versions changed this
interface to one without the
.I len
field, and still later versions reverted again. The glibc prototype is now
.sp
.nf
/* Set the CPU affinity for a task */
extern int sched_setaffinity (pid_t pid, size_t cpusetsize,
                              const cpu_set_t *cpuset);
.sp
/* Get the CPU affinity for a task */
extern int sched_getaffinity (pid_t pid, size_t cpusetsize,
                              cpu_set_t *cpuset);
.fi
.SH "SEE ALSO"
.BR clone (2),
.BR getpriority (2),
.BR gettid (2),
.BR nice (2),
.BR sched_get_priority_max (2),
.BR sched_get_priority_min (2),
.BR sched_getscheduler (2),
.BR sched_setscheduler (2),
.BR setpriority (2),
.BR capabilities (7)
.PP
.BR sched_setscheduler (2)
has a description of the Linux scheduling scheme.