AFFINITY(3)

AFFINITY(3) | Library Functions Manual | AFFINITY(3)

# NAME

pthread_setaffinity_np, pthread_getaffinity_np — affinity of threads

# LIBRARY

POSIX Threads Library (libpthread, -lpthread)

# SYNOPSIS

#include <pthread.h>
#include <sched.h>
int
pthread_setaffinity_np(pthread_t thread, size_t size, cpuset_t *set);
int
pthread_getaffinity_np(pthread_t thread, size_t size, cpuset_t *set);

# DESCRIPTION

Thread affinity allows to run the thread on specified CPU or CPUs only.
The pthread_setaffinity_np() function sets the affinity mask set for thread. At least one valid CPU must be set in the mask.
The pthread_getaffinity_np() function gets the affinity mask of thread into set. Note that set must be created and initialized using the cpuset(3) functions.

# IMPLEMENTATION NOTES

Setting CPU pthread_setaffinity_np requires super-user privileges. Ordinary users can be allowed to control CPU affinity of their threads via the security.models.extensions.user_set_cpu_affinity sysctl(7). See secmodel_extensions(9).
Portable applications should not use the pthread_setaffinity_np() and pthread_getaffinity_np() functions.

# RETURN VALUES

The pthread_setaffinity_np() and pthread_getaffinity_np() functions return 0 on success. Otherwise, an error number is returned to indicate the error.

# EXAMPLES

An example of code fragment, which sets the affinity for the current thread to the CPU whose ID is 0:

    	cpuset_t *cset;
    	pthread_t pth;
    	cpuid_t ci;

    	cset = cpuset_create();
    	if (cset == NULL) {
    		err(EXIT_FAILURE, "cpuset_create");
    	}
    	ci = 0;
    	cpuset_set(ci, cset);

    	pth = pthread_self();
    	error = pthread_setaffinity_np(pth, cpuset_size(cset), cset);
    	if (error) {
    		...
    	}
    	cpuset_destroy(cset);

# COMPATIBILITY

Both functions are non-standard extensions.

# ERRORS

Both functions may fail if:

[`EINVAL`]
  The specified set was invalid.
[`EPERM`]
  The calling process lacks the appropriate privileges to perform the operation.
[`ESRCH`]
  No thread could be found corresponding to the one specified by thread.

# NOTES

There is an alternative processor sets interface, see pset(3). However, thread affinity and processor sets are mutually exclusive, hence mixing of these interfaces is prohibited.

# SEE ALSO

cpuset(3), pset(3), pthread_getschedparam(3), pthread_setschedparam(3), sched(3), schedctl(8)

December 4, 2011 | NetBSD 8.3