mirror of https://github.com/mkerrisk/man-pages
pthread_setaffinity_np.3: New page for pthread_setaffinity_np(3) and pthread_getaffinity_np(3)
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
d84d0300a5
commit
5655765fdd
|
@ -0,0 +1,188 @@
|
|||
.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
|
||||
.\" <mtk.manpages@gmail.com>
|
||||
.\"
|
||||
.\" Permission is granted to make and distribute verbatim copies of this
|
||||
.\" manual provided the copyright notice and this permission notice are
|
||||
.\" preserved on all copies.
|
||||
.\"
|
||||
.\" Permission is granted to copy and distribute modified versions of this
|
||||
.\" manual under the conditions for verbatim copying, provided that the
|
||||
.\" entire resulting derived work is distributed under the terms of a
|
||||
.\" permission notice identical to this one.
|
||||
.\"
|
||||
.\" Since the Linux kernel and libraries are constantly changing, this
|
||||
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
||||
.\" responsibility for errors or omissions, or for damages resulting from
|
||||
.\" the use of the information contained herein. The author(s) may not
|
||||
.\" have taken the same level of care in the production of this manual,
|
||||
.\" which is licensed free of charge, as they might when working
|
||||
.\" professionally.
|
||||
.\"
|
||||
.\" Formatted or processed versions of this manual, if unaccompanied by
|
||||
.\" the source, must acknowledge the copyright and authors of this work.
|
||||
.\"
|
||||
.TH PTHREAD_SETAFFINITY_NP 3 2008-11-04 "Linux" "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
pthread_setaffinity_np, pthread_getaffinity_np \- set/get
|
||||
CPU affinity of a thread
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
.B #define _GNU_SOURCE
|
||||
.B #include <pthread.h>
|
||||
|
||||
.BI "int pthread_setaffinity_np(pthread_t " thread ", size_t " cpusetsize ,
|
||||
.BI " const cpu_set_t *" cpuset );
|
||||
.BI "int pthread_getaffinity_np(pthread_t " thread ", size_t " cpusetsize ,
|
||||
.BI " cpu_set_t *" cpuset );
|
||||
.sp
|
||||
Compile and link with \fI\-pthread\fP.
|
||||
.SH DESCRIPTION
|
||||
The
|
||||
.BR pthread_setaffinity_np ()
|
||||
sets the CPU affinity mask of the thread
|
||||
.I thread
|
||||
to the CPU set pointed to by
|
||||
.IR cpuset .
|
||||
If the call is successful,
|
||||
and the thread is not currently running on one of the CPUs in
|
||||
.IR cpuset ,
|
||||
then it is migrated to one of those CPUs.
|
||||
|
||||
The
|
||||
.BR pthread_getaffinity_np ()
|
||||
function returns the CPU affinity mask of the thread
|
||||
.I thread
|
||||
in the buffer pointed to by
|
||||
.IR cpuset .
|
||||
|
||||
The argument
|
||||
.I cpusetsize
|
||||
is the length (in bytes) of the buffer pointed to by
|
||||
.IR cpuset .
|
||||
Normally this argument would be specified as
|
||||
.IR sizeof(cpu_set_t) .
|
||||
The constant
|
||||
.B CPU_SETSIZE
|
||||
specifies a value one greater than the
|
||||
maximum CPU number that can be stored in a CPU set.
|
||||
|
||||
For more details on CPU affinity masks,
|
||||
as well as a description of a set of macros
|
||||
that can be used to manipulate and inspect CPU sets, see
|
||||
.BR sched_setaffinity (2)
|
||||
for details.
|
||||
.SH RETURN VALUE
|
||||
On success, these functions return 0;
|
||||
on error, they return a non-zero error number.
|
||||
.SH ERRORS
|
||||
.TP
|
||||
.B EFAULT
|
||||
A supplied memory address was invalid.
|
||||
.TP
|
||||
.B EINVAL
|
||||
.RB ( pthread_setaffinity_np ())
|
||||
The affinity bit mask
|
||||
.I mask
|
||||
contains no processors that are physically on the system.
|
||||
.TP
|
||||
.BR EINVAL
|
||||
.RB ( pthread_setaffinity_np ())
|
||||
.I cpuset
|
||||
specified a CPU that was outside the range
|
||||
permitted by the kernel data type
|
||||
.\" cpumask_t
|
||||
used to represent CPU sets.
|
||||
.\" The raw sched_getaffinity() system call returns the size (in bytes)
|
||||
.\" of the cpumask_t type.
|
||||
This range is determined by the kernel configuration option
|
||||
.BR CONFIG_NR_CPUS .
|
||||
.TP
|
||||
.B EINVAL
|
||||
.RB ( pthread_getaffinity_np ()
|
||||
.I cpusetsize
|
||||
is smaller than the size of the affinity mask used by the kernel.
|
||||
.TP
|
||||
.B ESRCH
|
||||
There is no thread matching
|
||||
.IR thread
|
||||
(e.g., perhaps that thread has already terminated and been joined).
|
||||
.SH VERSIONS
|
||||
These functions are provided by glibc since version 2.3.4.
|
||||
.SH CONFORMING TO
|
||||
These functions are non-standard GNU extensions.
|
||||
.SH NOTES
|
||||
These functions are implemented on top of the
|
||||
.BR sched_setaffinity (2)
|
||||
and
|
||||
.BR sched_getaffinity (2)
|
||||
system calls.
|
||||
|
||||
In glibc 2.3.3 only,
|
||||
versions of these functions were provided that did not have a
|
||||
.I cpusetsize
|
||||
argument.
|
||||
Instead the CPU set size given to the underlying system calls was always
|
||||
.IR sizeof(cpu_set_t) .
|
||||
|
||||
A new thread created by
|
||||
.BR pthread_create ()
|
||||
inherits a copy of its creator's CPU affinity mask.
|
||||
.SH EXAMPLE
|
||||
In the following program, the main thread uses
|
||||
.BR pthread_setaffinity_np ()
|
||||
to set its CPU affinity mask to include CPUs 0 to 7
|
||||
(which may not all be available on the system),
|
||||
and then calls
|
||||
.BR pthread_getaffinity_np ()
|
||||
to check the resulting CPU affinity mask of the thread.
|
||||
|
||||
.nf
|
||||
#define _GNU_SOURCE
|
||||
#include <pthread.h>
|
||||
#include <stdio.h>
|
||||
#include <stdlib.h>
|
||||
#include <errno.h>
|
||||
|
||||
#define errExitEN(en, msg) { errno = en; perror(msg); \\
|
||||
exit(EXIT_FAILURE); }
|
||||
int
|
||||
main(int argc, char *argv[])
|
||||
{
|
||||
int s, j;
|
||||
cpu_set_t cpuset;
|
||||
pthread_t thread;
|
||||
|
||||
thread = pthread_self();
|
||||
|
||||
/* Set affinity mask to include CPUs 0 to 7 */
|
||||
|
||||
CPU_ZERO(&cpuset);
|
||||
for (j = 0; j < 8; j++)
|
||||
CPU_SET(j, &cpuset);
|
||||
|
||||
s = pthread_setaffinity_np(thread, sizeof(cpu_set_t), &cpuset);
|
||||
if (s != 0)
|
||||
errExitEN(s, "sched_setaffinity");
|
||||
|
||||
/* Check the actual affinity mask assigned to the thread */
|
||||
|
||||
s = pthread_getaffinity_np(thread, sizeof(cpu_set_t), &cpuset);
|
||||
if (s != 0)
|
||||
errExitEN(s, "sched_getaffinity");
|
||||
|
||||
printf("Set returned by pthread_getaffinity_np() contained:\\n");
|
||||
for (j = 0; j < CPU_SETSIZE; j++)
|
||||
if (CPU_ISSET(j, &cpuset))
|
||||
printf(" CPU %d\\n", j);
|
||||
|
||||
exit(EXIT_SUCCESS);
|
||||
}
|
||||
.fi
|
||||
.SH SEE ALSO
|
||||
.BR sched_getaffinity (2),
|
||||
.BR sched_setaffinity (2),
|
||||
.BR sched_getscheduler (2),
|
||||
.BR pthread_getaffinity_np (3),
|
||||
.BR pthread_setaffinity_np (3),
|
||||
.BR cpuset (7),
|
||||
.BR pthreads (7)
|
Loading…
Reference in New Issue