diff options
| -rw-r--r-- | man3/pthread_setaffinity_np.3 | 188 |
1 files changed, 188 insertions, 0 deletions
diff --git a/man3/pthread_setaffinity_np.3 b/man3/pthread_setaffinity_np.3 new file mode 100644 index 0000000000..06a26884fb --- /dev/null +++ b/man3/pthread_setaffinity_np.3 @@ -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) |