2004-11-03 13:51:07 +00:00
|
|
|
.\" man2/sched_setaffinity.2 - sched_setaffinity and sched_getaffinity man page
|
|
|
|
.\"
|
|
|
|
.\" Copyright (C) 2002 Robert Love
|
2006-05-22 23:52:24 +00:00
|
|
|
.\" and Copyright (C) 2006 Michael Kerrisk
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
|
|
|
.\" 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
|
2007-04-12 22:42:49 +00:00
|
|
|
.\" 2005-05-03 mtk - noted that sched_setaffinity may cause thread
|
2005-05-03 14:24:08 +00:00
|
|
|
.\" migration and that CPU affinity is a per-thread attribute.
|
2006-02-02 19:46:34 +00:00
|
|
|
.\" 2006-02-03 mtk -- Major rewrite
|
2008-11-12 18:26:47 +00:00
|
|
|
.\" 2008-11-12, mtk, removed CPU_*() macro descriptions to a
|
|
|
|
.\" separate CPU_SET(3) page.
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
2010-11-06 16:36:15 +00:00
|
|
|
.TH SCHED_SETAFFINITY 2 2010-11-06 "Linux" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
2008-11-12 18:26:47 +00:00
|
|
|
sched_setaffinity, sched_getaffinity \- \
|
|
|
|
set and get a process's CPU affinity mask
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH SYNOPSIS
|
2006-05-01 23:05:09 +00:00
|
|
|
.nf
|
accept.2, clone.2, dup.2, fallocate.2, pipe.2, readahead.2, sched_setaffinity.2, unshare.2, CPU_SET.3, endian.3, euidaccess.3, fexecve.3, getpt.3, getpw.3, getumask.3, getutmp.3, gnu_get_libc_version.3, makedev.3, matherr.3, mbsnrtowcs.3, memfrob.3, pthread_attr_setaffinity_np.3, pthread_getattr_np.3, pthread_setaffinity_np.3, pthread_tryjoin_np.3, tcgetsid.3, wcscasecmp.3, wcsncasecmp.3, wcsnlen.3, wcsnrtombs.3, wcswidth.3, rtld-audit.7: SYNOPSIS: Add reference to feature_test_macros(7)
These pages specify feature test macros in the function
prototypes. Add a reference to feature_test_macros(7),
so that readers are pointed to the information that
feature test macros must be defined before including
*any* header file.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-09-10 05:06:22 +00:00
|
|
|
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
|
2004-11-03 13:51:07 +00:00
|
|
|
.B #include <sched.h>
|
|
|
|
.sp
|
2008-07-08 18:22:31 +00:00
|
|
|
.BI "int sched_setaffinity(pid_t " pid ", size_t " cpusetsize ,
|
2006-05-01 23:05:09 +00:00
|
|
|
.BI " cpu_set_t *" mask );
|
2004-11-03 13:51:07 +00:00
|
|
|
.sp
|
2008-07-08 18:22:31 +00:00
|
|
|
.BI "int sched_getaffinity(pid_t " pid ", size_t " cpusetsize ,
|
2006-05-01 23:05:09 +00:00
|
|
|
.BI " cpu_set_t *" mask );
|
|
|
|
.fi
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH DESCRIPTION
|
2006-02-02 19:46:34 +00:00
|
|
|
A process's CPU affinity mask determines the set of CPUs on which
|
|
|
|
it is eligible to run.
|
|
|
|
On a multiprocessor system, setting the CPU affinity mask
|
2007-04-12 22:42:49 +00:00
|
|
|
can be used to obtain performance benefits.
|
2006-02-02 19:46:34 +00:00
|
|
|
For example,
|
2007-04-12 22:42:49 +00:00
|
|
|
by dedicating one CPU to a particular process
|
|
|
|
(i.e., setting the affinity mask of that process to specify a single CPU,
|
|
|
|
and setting the affinity mask of all other processes to exclude that CPU),
|
2006-02-02 19:46:34 +00:00
|
|
|
it is possible to ensure maximum execution speed for that process.
|
2008-11-12 17:08:34 +00:00
|
|
|
Restricting a process to run on a single CPU also avoids
|
2007-04-12 22:42:49 +00:00
|
|
|
the performance cost caused by the cache invalidation that occurs
|
|
|
|
when a process ceases to execute on one CPU and then
|
2006-02-02 19:46:34 +00:00
|
|
|
recommences execution on a different CPU.
|
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
A CPU affinity mask is represented by the
|
|
|
|
.I cpu_set_t
|
2006-02-02 19:46:34 +00:00
|
|
|
structure, a "CPU set", pointed to by
|
|
|
|
.IR mask .
|
2008-11-12 18:26:47 +00:00
|
|
|
A set of macros for manipulating CPU sets is described in
|
|
|
|
.BR CPU_SET (3).
|
2006-02-02 19:46:34 +00:00
|
|
|
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR sched_setaffinity ()
|
2006-02-02 19:46:34 +00:00
|
|
|
sets the CPU affinity mask of the process whose ID is
|
2007-09-20 16:26:31 +00:00
|
|
|
.I pid
|
2006-02-02 19:46:34 +00:00
|
|
|
to the value specified by
|
|
|
|
.IR mask .
|
2004-11-03 13:51:07 +00:00
|
|
|
If
|
|
|
|
.I pid
|
2006-02-02 19:46:34 +00:00
|
|
|
is zero, then the calling process is used.
|
|
|
|
The argument
|
|
|
|
.I cpusetsize
|
|
|
|
is the length (in bytes) of the data pointed to by
|
2004-11-03 13:51:07 +00:00
|
|
|
.IR mask .
|
2006-02-02 19:46:34 +00:00
|
|
|
Normally this argument would be specified as
|
|
|
|
.IR "sizeof(cpu_set_t)" .
|
2006-02-02 18:15:36 +00:00
|
|
|
|
2005-05-03 11:24:33 +00:00
|
|
|
If the process specified by
|
|
|
|
.I pid
|
2006-02-02 19:46:34 +00:00
|
|
|
is not currently running on one of the CPUs specified in
|
2005-05-03 11:24:33 +00:00
|
|
|
.IR mask ,
|
|
|
|
then that process is migrated to one of the CPUs specified in
|
|
|
|
.IR mask .
|
2006-02-02 19:46:34 +00:00
|
|
|
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR sched_getaffinity ()
|
2006-02-02 19:46:34 +00:00
|
|
|
writes the affinity mask of the process whose ID is
|
2007-09-20 16:26:31 +00:00
|
|
|
.I pid
|
2007-04-12 22:42:49 +00:00
|
|
|
into the
|
2006-02-02 19:46:34 +00:00
|
|
|
.I cpu_set_t
|
|
|
|
structure pointed to by
|
|
|
|
.IR mask .
|
2007-04-12 22:42:49 +00:00
|
|
|
The
|
2006-02-02 19:46:34 +00:00
|
|
|
.I cpusetsize
|
|
|
|
argument specifies the size (in bytes) of
|
|
|
|
.IR mask .
|
2004-11-03 13:51:07 +00:00
|
|
|
If
|
|
|
|
.I pid
|
2006-02-02 19:46:34 +00:00
|
|
|
is zero, then the mask of the calling process is returned.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "RETURN VALUE"
|
|
|
|
On success,
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR sched_setaffinity ()
|
2006-02-02 19:46:34 +00:00
|
|
|
and
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR sched_getaffinity ()
|
2006-02-02 19:46:34 +00:00
|
|
|
return 0.
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
2007-07-01 04:23:34 +00:00
|
|
|
The affinity bit mask
|
2004-11-03 13:51:07 +00:00
|
|
|
.I mask
|
2008-11-14 15:35:45 +00:00
|
|
|
contains no processors that are currently physically on the system
|
|
|
|
and permitted to the process according to any restrictions that
|
|
|
|
may be imposed by the "cpuset" mechanism described in
|
|
|
|
.BR cpuset (7).
|
2008-11-04 22:00:02 +00:00
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
.RB ( sched_getaffinity ()
|
|
|
|
and, in kernels before 2.6.9,
|
|
|
|
.BR sched_setaffinity ())
|
2006-02-02 19:46:34 +00:00
|
|
|
.I cpusetsize
|
2004-11-03 13:51:07 +00:00
|
|
|
is smaller than the size of the affinity mask used by the kernel.
|
|
|
|
.TP
|
|
|
|
.B EPERM
|
2008-11-04 22:06:01 +00:00
|
|
|
.RB ( sched_setaffinity ())
|
2004-11-03 13:51:07 +00:00
|
|
|
The calling process does not have appropriate privileges.
|
2010-11-06 16:36:15 +00:00
|
|
|
The caller needs an effective user ID equal to the real user ID
|
2008-11-04 22:06:01 +00:00
|
|
|
or effective user ID of the process identified by
|
2004-11-03 13:51:07 +00:00
|
|
|
.IR pid ,
|
|
|
|
or it must possess the
|
2007-09-20 16:26:31 +00:00
|
|
|
.B CAP_SYS_NICE
|
2004-11-03 13:51:07 +00:00
|
|
|
capability.
|
|
|
|
.TP
|
|
|
|
.B ESRCH
|
2007-07-18 20:24:30 +00:00
|
|
|
The process whose ID is \fIpid\fP could not be found.
|
2007-05-18 16:06:42 +00:00
|
|
|
.SH VERSIONS
|
|
|
|
The CPU affinity system calls were introduced in Linux kernel 2.5.8.
|
2008-11-12 17:07:41 +00:00
|
|
|
The system call wrappers were introduced in glibc 2.3.
|
2007-05-18 16:06:42 +00:00
|
|
|
Initially, the glibc interfaces included a
|
|
|
|
.I cpusetsize
|
2008-07-08 18:22:31 +00:00
|
|
|
argument, typed as
|
|
|
|
.IR "unsigned int" .
|
2007-05-18 16:06:42 +00:00
|
|
|
In glibc 2.3.3, the
|
|
|
|
.I cpusetsize
|
2008-07-08 18:22:31 +00:00
|
|
|
argument was removed, but was then restored in glibc 2.3.4, with type
|
|
|
|
.IR size_t .
|
2006-02-02 19:46:34 +00:00
|
|
|
.SH "CONFORMING TO"
|
2007-12-25 21:28:09 +00:00
|
|
|
These system calls are Linux-specific.
|
2005-05-03 14:24:08 +00:00
|
|
|
.SH "NOTES"
|
2008-11-14 15:35:45 +00:00
|
|
|
After a call to
|
|
|
|
.BR sched_setaffinity (),
|
|
|
|
the set of CPUs on which the process will actually run is
|
|
|
|
the intersection of the set specified in the
|
|
|
|
.I mask
|
|
|
|
argument and the set of CPUs actually present on the system.
|
|
|
|
The system may further restrict the set of CPUs on which the process
|
|
|
|
runs if the "cpuset" mechanism described in
|
|
|
|
.BR cpuset (7)
|
|
|
|
is being used.
|
|
|
|
These restrictions on the actual set of CPUs on which the process
|
|
|
|
will run are silently imposed by the kernel.
|
|
|
|
|
2007-12-17 11:24:05 +00:00
|
|
|
.BR sched_setscheduler (2)
|
|
|
|
has a description of the Linux scheduling scheme.
|
|
|
|
.PP
|
2005-05-03 14:24:08 +00:00
|
|
|
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 .
|
2007-07-21 06:59:36 +00:00
|
|
|
Specifying
|
|
|
|
.I pid
|
2008-11-13 19:38:10 +00:00
|
|
|
as 0 will set the attribute for the calling thread,
|
2007-07-21 06:59:36 +00:00
|
|
|
and passing the value returned from a call to
|
|
|
|
.BR getpid (2)
|
|
|
|
will set the attribute for the main thread of the thread group.
|
2008-11-13 19:38:45 +00:00
|
|
|
(If you are using the POSIX threads API, then use
|
2009-09-27 07:26:31 +00:00
|
|
|
.BR pthread_setaffinity_np (3)
|
2008-11-26 02:44:53 +00:00
|
|
|
instead of
|
2008-11-13 19:38:45 +00:00
|
|
|
.BR sched_setaffinity ().)
|
2006-02-02 19:46:34 +00:00
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
A child created via
|
2006-02-02 19:46:34 +00:00
|
|
|
.BR fork (2)
|
|
|
|
inherits its parent's CPU affinity mask.
|
|
|
|
The affinity mask is preserved across an
|
|
|
|
.BR execve (2).
|
|
|
|
|
|
|
|
This manual page describes the glibc interface for the CPU affinity calls.
|
2007-04-12 22:42:49 +00:00
|
|
|
The actual system call interface is slightly different, with the
|
2006-02-02 19:46:34 +00:00
|
|
|
.I mask
|
|
|
|
being typed as
|
|
|
|
.IR "unsigned long *" ,
|
2008-11-04 18:56:30 +00:00
|
|
|
reflecting the fact that the underlying implementation of CPU
|
2007-07-01 04:23:34 +00:00
|
|
|
sets is a simple bit mask.
|
2007-04-12 22:42:49 +00:00
|
|
|
On success, the raw
|
2006-02-02 19:46:34 +00:00
|
|
|
.BR sched_getaffinity ()
|
2007-04-12 22:42:49 +00:00
|
|
|
system call returns the size (in bytes) of the
|
2006-02-02 19:46:34 +00:00
|
|
|
.I cpumask_t
|
2007-04-12 22:42:49 +00:00
|
|
|
data type that is used internally by the kernel to
|
2007-07-01 04:23:34 +00:00
|
|
|
represent the CPU set bit mask.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "SEE ALSO"
|
2005-05-03 14:24:08 +00:00
|
|
|
.BR clone (2),
|
2008-07-03 12:20:42 +00:00
|
|
|
.BR getcpu (2),
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR getpriority (2),
|
2005-05-03 14:24:08 +00:00
|
|
|
.BR gettid (2),
|
2004-11-03 13:51:07 +00:00
|
|
|
.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),
|
2008-11-12 18:26:47 +00:00
|
|
|
.BR CPU_SET (3),
|
clock_nanosleep.2, getpriority.2, kexec_load.2, nanosleep.2, nice.2, sched_setaffinity.2, timer_create.2, timer_delete.2, timer_settime.2, utime.2, btowc.3, futimes.3, log.3, pthread_attr_setguardsize.3, pthread_kill_other_threads_np.3, pthread_setaffinity_np.3, pthread_setcancelstate.3, pthread_setschedparam.3, pthread_setschedprio.3, pthread_tryjoin_np.3, strcoll.3, strcpy.3, string.3, strxfrm.3, networks.5, aio.7, sigevent.7, udplite.7: SEE ALSO: Place entries in correct order
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-11-01 05:34:26 +00:00
|
|
|
.BR pthread_setaffinity_np (3),
|
2008-11-06 14:10:50 +00:00
|
|
|
.BR sched_getcpu (3),
|
2008-06-17 08:32:41 +00:00
|
|
|
.BR capabilities (7),
|
|
|
|
.BR cpuset (7)
|