PTHREAD_ATTR_AFFINITY_NP(3)

NAME
pthread_attr_getaffinity_np, pthread_attr_setaffinity_np - manage CPU affinity in thread attribute objects

LIBRARY
libpthread

SYNOPSIS
#include <pthread_np.h>
int
pthread_attr_getaffinity_np(const pthread_attr_t *pattr, size_t cpusetsize, cpuset_t *cpusetp);
int
pthread_attr_setaffinity_np(pthread_attr_t *pattr, size_t cpusetsize, const cpuset_t *cpusetp);

DESCRIPTION
The pthread_attr_getaffinity_np() and pthread_attr_setaffinity_np() functions allow the manipulation of sets of CPUs available to the specified thread attribute object.

Masks of type cpuset_t are composed using the CPU_SET macros. If the user-supplied mask is not large enough to fit all of the matching CPUs, pthread_attr_getaffinity_np() fails with ERANGE. Calls to pthread_attr_setaffinity_np() tolerate masks of any size with no restrictions. pthread_attr_setaffinity_np() uses the meaningful part of the mask, where the upper bound is the maximum CPU id present in the system. If bits for non-existing CPUs are set, calls to pthread_attr_setaffinity_np() fail with EINVAL.

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_attr_getaffinity_np() retrieves the mask from the thread attribute object specified by pattr, and stores it in the space provided by cpusetp.

pthread_attr_setaffinity_np() sets the mask for the thread attribute object specified by pattr to the value in cpusetp.

RETURN VALUES
If successful, the pthread_attr_getaffinity_np() and pthread_attr_setaffinity_np() functions will return zero. Otherwise an error number will be returned to indicate the error.

ERRORS
The pthread_attr_getaffinity_np() functions will fail if:

[EINVAL]
    The pattr or the attribute specified by it is NULL.

[ERANGE]
    The cpusetsize is too small.

The pthread_attr_setaffinity_np() function will fail if:

[EINVAL]
    The pattr or the attribute specified by it is NULL.

[EINVAL]
    The cpusetp specified a CPU that was outside the set supported by the kernel.

[ENOMEM]
    Insufficient memory exists to store the cpuset mask.

SEE ALSO
cpuset(1), cpuset(2), cpuset_getid(2), cpuset_setid(2), pthread_getaffinity_np(3), pthread_np(3), pthread_setaffinity_np(3)

STANDARDS
The pthread_attr_getaffinity_np and pthread_attr_setaffinity_np functions are non-standard FreeBSD extensions and may be not available on other operating systems.

HISTORY
The pthread_attr_getaffinity_np and pthread_attr_setaffinity_np functions first appeared in FreeBSD 7.2.

AUTHORS
-nosplit The pthread_attr_getaffinity_np and pthread_attr_setaffinity_np functions were written by David Xu <davidxu@FreeBSD.org>, and this manpage was written by Xin LI <delphij@FreeBSD.org>.