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;
    	int error;

    	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) {
    		errc(EXIT_FAILURE, error, "pthread_setaffinity_np failed");
    	}
    	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)

February 21, 2025 | NetBSD 11.0