home | help 
PTHREAD_AFFINITY_NP(3)	     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 manipula-
     tion of sets of CPUs available to the specified thread.

     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_getaffinity_np()  fails  with  ERANGE.   Calls to pthread_setaffin-
     ity_np() tolerate masks of any size with no restrictions.	The kernel  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_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_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:

     [EINVAL]		The    cpusetp	  argument    specified   when	 calling
			pthread_setaffinity_np() was not a valid value.

     [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 smaller than needed to fit all of the
			matching CPUs.

     [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),
     pthread_np(3)

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

HISTORY
     The  pthread_getaffinity_np  and  pthread_setaffinity_np function first ap-
     peared in FreeBSD 7.2.

AUTHORS
     The pthread_getaffinity_np and pthread_setaffinity_np functions were  writ-
     ten  by David Xu <davidxu@FreeBSD.org>, and this manpage was written by Xin
     LI <delphij@FreeBSD.org>.

FreeBSD 15.1			January 29, 2023	  PTHREAD_AFFINITY_NP(3)
home | help