PTHREAD_AFFINITY_NP(3) BSD Library Functions Manual PTHREAD_AFFINITY_NP(3)NAME
pthread_getaffinity_np, pthread_setaffinity_np -- manage CPU affinity
LIBRARY
POSIX Threads Library (libpthread, -lpthread)
SYNOPSIS
#include <pthread_np.h>
int
pthread_getaffinity_np(pthread_t td, size_t cpusetsize, cpuset_t *cpusetp);
int
pthread_setaffinity_np(pthread_t td, size_t cpusetsize, const cpuset_t *cpusetp);
DESCRIPTION
pthread_getaffinity_np() and pthread_setaffinity_np() allow the manipulation of sets of CPUs available to the specified thread.
Masks of type cpuset_t are composed using the CPU_SET macros. The kernel tolerates large sets as long as all CPUs specified in the set
exist. Sets smaller than the kernel uses generate an error on calls to pthread_getaffinity_np() even if the result set would fit within the
user supplied set. Calls to pthread_setaffinity_np() tolerate small sets with no restrictions.
The supplied mask should have a size of cpusetsize bytes. This size is usually provided by calling sizeof(cpuset_t) which is ultimately
determined by the value of CPU_SETSIZE as defined in <sys/cpuset.h>.
pthread_getaffinity_np() retrieves the mask from the thread specified by td, and stores it in the space provided by cpusetp.
pthread_setaffinity_np() attempts to set the mask for the thread specified by td to the value in cpusetp.
RETURN VALUES
If successful, the pthread_getaffinity_np() and pthread_setaffinity_np() functions will return zero. Otherwise an error number will be
returned to indicate the error.
ERRORS
The pthread_getaffinity_np() and pthread_setaffinity_np() functions may fail if:
[EDEADLK] The pthread_setaffinity_np() call would leave a thread without a valid CPU to run on because the set does not overlap with
the thread's anonymous mask.
[EFAULT] The cpusetp pointer passed was invalid.
[ESRCH] The thread specified by the td argument could not be found.
[ERANGE] The cpusetsize was either preposterously large or smaller than the kernel set size.
[EPERM] The calling thread did not have the credentials required to complete the operation.
SEE ALSO cpuset(1), cpuset(2), cpuset_getid(2), cpuset_setid(2), pthread(3), pthread_attr_getaffinity_np(3), pthread_attr_setaffinity_np(3)STANDARDS
The pthread_getaffinity_np and pthread_setaffinity_np functions are non-standard FreeBSD extensions and may be not available on other operat-
ing systems.
HISTORY
The pthread_getaffinity_np and pthread_setaffinity_np function first appeared in FreeBSD 7.2.
AUTHORS
The pthread_getaffinity_np and pthread_setaffinity_np functions were written by David Xu <davidxu@FreeBSD.org>, and this manpage was written
by Xin LI <delphij@FreeBSD.org>.
BSD March 23, 2010 BSD
Check Out this Related Man Page
PTHREAD_SETAFFINITY_NP(3) Linux Programmer's Manual PTHREAD_SETAFFINITY_NP(3)NAME
pthread_setaffinity_np, pthread_getaffinity_np - set/get CPU affinity of a thread
SYNOPSIS
#define _GNU_SOURCE /* See feature_test_macros(7) */
#include <pthread.h>
int pthread_setaffinity_np(pthread_t thread, size_t cpusetsize,
const cpu_set_t *cpuset);
int pthread_getaffinity_np(pthread_t thread, size_t cpusetsize,
cpu_set_t *cpuset);
Compile and link with -pthread.
DESCRIPTION
The pthread_setaffinity_np() function sets the CPU affinity mask of the thread thread to the CPU set pointed to by cpuset. If the call is
successful, and the thread is not currently running on one of the CPUs in cpuset, then it is migrated to one of those CPUs.
The pthread_getaffinity_np() function returns the CPU affinity mask of the thread thread in the buffer pointed to by cpuset.
For more details on CPU affinity masks, see sched_setaffinity(2). For a description of a set of macros that can be used to manipulate and
inspect CPU sets, see CPU_SET(3).
The argument cpusetsize is the length (in bytes) of the buffer pointed to by cpuset. Typically, this argument would be specified as
sizeof(cpu_set_t). (It may be some other value, if using the macros described in CPU_SET(3) for dynamically allocating a CPU set.)
RETURN VALUE
On success, these functions return 0; on error, they return a nonzero error number.
ERRORS
EFAULT A supplied memory address was invalid.
EINVAL (pthread_setaffinity_np()) The affinity bit mask mask contains no processors that are currently physically on the system and permit-
ted to the thread according to any restrictions that may be imposed by the "cpuset" mechanism described in cpuset(7).
EINVAL (pthread_setaffinity_np()) cpuset specified a CPU that was outside the set supported by the kernel. (The kernel configuration
option CONFIG_NR_CPUS defines the range of the set supported by the kernel data type used to represent CPU sets.)
EINVAL (pthread_getaffinity_np()) cpusetsize is smaller than the size of the affinity mask used by the kernel.
ESRCH No thread with the ID thread could be found.
VERSIONS
These functions are provided by glibc since version 2.3.4.
CONFORMING TO
These functions are nonstandard GNU extensions; hence the suffix "_np" (nonportable) in the names.
NOTES
After a call to pthread_setaffinity_np(), the set of CPUs on which the thread will actually run is the intersection of the set specified in
the cpuset argument and the set of CPUs actually present on the system. The system may further restrict the set of CPUs on which the
thread runs if the "cpuset" mechanism described in cpuset(7) is being used. These restrictions on the actual set of CPUs on which the
thread will run are silently imposed by the kernel.
These functions are implemented on top of the sched_setaffinity(2) and sched_getaffinity(2) system calls.
In glibc 2.3.3 only, versions of these functions were provided that did not have a cpusetsize argument. Instead the CPU set size given to
the underlying system calls was always sizeof(cpu_set_t).
A new thread created by pthread_create() inherits a copy of its creator's CPU affinity mask.
EXAMPLE
In the following program, the main thread uses 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 pthread_getaffinity_np() to check the resulting CPU affinity mask of the thread.
#define _GNU_SOURCE
#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>
#include <errno.h>
#define handle_error_en(en, msg)
do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
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)
handle_error_en(s, "pthread_setaffinity_np");
/* Check the actual affinity mask assigned to the thread */
s = pthread_getaffinity_np(thread, sizeof(cpu_set_t), &cpuset);
if (s != 0)
handle_error_en(s, "pthread_getaffinity_np");
printf("Set returned by pthread_getaffinity_np() contained:
");
for (j = 0; j < CPU_SETSIZE; j++)
if (CPU_ISSET(j, &cpuset))
printf(" CPU %d
", j);
exit(EXIT_SUCCESS);
}
SEE ALSO sched_getcpu(3), sched_setaffinity(2), sched_setscheduler(2), pthread_attr_setaffinity_np(3), pthread_self(3), cpuset(7), pthreads(7)COLOPHON
This page is part of release 3.27 of the Linux man-pages project. A description of the project, and information about reporting bugs, can
be found at http://www.kernel.org/doc/man-pages/.
Linux 2010-09-10 PTHREAD_SETAFFINITY_NP(3)