PTHREAD_ATTR_AFFINITY_NP(3)

okay so bestie, welcome to PTHREAD_ATTR_AFFINITY_NP(3) — the Library Functions Manual page for two little FreeBSD-flavored baddies that manage CPU affinity inside thread attribute objects 💅✨. If you’ve ever wanted to tell a thread “these are your CPUs, periodt,” this is the page. Let’s get into it.

✨ NAME ✨

pthread_attr_getaffinity_np, pthread_attr_setaffinity_np — manage CPU affinity in thread attribute objects.

📚 LIBRARY 📚

POSIX Threads Library (libpthread, -lpthread). Link it and go off 💖.

🌸 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. Basically: CPU sets, but for a thread attribute object, and yes they’re siblings 👯.

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. That last bit is lowkey important — no imaginary CPUs, bestie 🚫💀.

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. Zero = the vibe check passed ✅; nonzero = something’s off 😭.

😭 ERRORS 😭

The pthread_attr_getaffinity_np() function 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)

Go read these next if you’re in your Unix research era 🔥.

🌈 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. So like, don’t expect this exact flavor everywhere — it’s giving FreeBSD-specific 🫶.

👑 HISTORY 👑

The pthread_attr_getaffinity_np and pthread_attr_setaffinity_np functions first appeared in FreeBSD 7.2. A little vintage, a little iconic 💅.

🎀 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>. Shoutout to the icons who wrote the code and the page 🫶✨.

---

Debian source/version says this edition is dated January 29, 2023 — xoxo, your Unix bestie 💖