On Tue, Nov 4, 2008 at 23:47, Michael Kerrisk <mtk.manpages@xxxxxxxxxxxxxx> wrote: > Hi all, > > Another new pthreads man page looking for reviewers. > > Cheers, > > Michael > > .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk > .\" <mtk.manpages@xxxxxxxxx> > .\" > .\" 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. Yeah, I like this naming confusion: http://sourceware.org/ml/libc-alpha/2008-03/msg00080.html > > 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. Maybe a more detailed hint is needed, that cpumask_t and cpu_set_t are the 'same', the former inside the kernel the latter in user space. But I think such deep kernel internals doesn't belong to a API description (because cpumask_t may gone, see 'struct cpumask' patches). I would just replace cpumask_t by cpu_set_t. > 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 interpreted 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), Maybe pthread__attr_{set,get}affinity_np, too. > .BR cpuset (7), > .BR pthreads (7) > -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
