PTHREAD_AFFINITY_NP(3)

📦 version 15.1, in freebsd 14.5, freebsd 15.1, nixpkgs unstable

💫 PTHREAD_AFFINITY_NP(3) 💫

okay so bestie, let's talk about managing CPU affinity 💅 this is part of the POSIX Threads Library (libpthread, -lpthread) and it's giving "I control which CPUs my threads run on" energy ✨

🌸 SYNOPSIS 🌸

like, here's the vibe of what we're working with:

#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 🦋

ngl, pthread_getaffinity_np() and pthread_setaffinity_np() are your besties for manipulating sets of CPUs available to a specified thread 💖

so, masks of type cpuset_t? they're composed using the CPU_SET macros 🎀 and like, if your user-supplied mask isn't large enough to fit all the matching CPUs, pthread_getaffinity_np() will fail with ERANGE 😭 but pthread_setaffinity_np() is way more chill — it tolerates masks of any size with no restrictions, periodt ✨

the kernel uses the meaningful part of the mask, where the upper bound is the maximum CPU id present in the system. but like, if bits for non-existing CPUs are set? pthread_setaffinity_np() fails with EINVAL 💀 no cap.

your supplied mask should have a size of cpusetsize bytes, fr fr. 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 — it's literally giving "I got you, let me grab that data" energy 🫶

pthread_setaffinity_np() attempts to set the mask for the thread specified by td to the value in cpusetp — like, it's the setter bestie, the one that actually makes changes happen 💅

🔥 RETURN VALUES 🔥

if successful, pthread_getaffinity_np() and pthread_setaffinity_np() will return zero — slay! 👑

otherwise, an error number will be returned to indicate the error 😔 sad vibes but at least you know what's up.

💀 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. like, it's giving "invalid input" energy 🙈
  • [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. that's highkey a deadlock situation and we don't stan 😭
  • [EFAULT] — the cpusetp pointer passed was invalid. bad pointer vibes, not cute 💔
  • [ESRCH] — the thread specified by the td argument could not be found. like, where did it go? ghosting us fr fr 👻
  • [ERANGE] — the cpusetsize was smaller than needed to fit all of the matching CPUs. the mask wasn't big enough to hold all the tea 🍵
  • [EPERM] — the calling thread did not have the credentials required to complete the operation. permission denied bestie, you don't have the keys to this VIP section 🚫

✨ SEE ALSO ✨

like, check out these other iconic pages:

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 not be available on other operating systems. like, it's giving "exclusive club" energy — FreeBSD only, iykyk 👑

🎀 HISTORY 🎀

the pthread_getaffinity_np and pthread_setaffinity_np functions first appeared in FreeBSD 7.2 — that's the origin story bestie 📖

👑 AUTHORS 👑

the pthread_getaffinity_np and pthread_setaffinity_np functions were written by David Xu <davidxu@FreeBSD.org>, and this manpage was written by Xin LI <delphij@FreeBSD.org>. legends only 💜

and that's the tea bestie! this page was brought to you by Debian on January 29, 2023 — stay slay, stay CPU-affine, and remember: always check your cpusetsize 💅✨

📦 where this page comes from