PTHREAD_ATTR_AFFINITY_NP(3)                   FreeBSD Library Functions Manual

NAME

     pthread_attr_getaffinity_np, pthread_attr_setaffinity_np - manage CPU
     affinity in thread attribute objects

LIBRARY

     POSIX Threads Library (libpthread, -lpthread)

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

     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>.

FreeBSD 15.1-STABLE-HBSD       January 29, 2023    PTHREAD_ATTR_AFFINITY_NP(3)