getpriority(2)

💖 getpriority(2) — the manual, but make it make sense 💖

okay bestie, sit down, hydrate, because we're about to learn how to get and set program scheduling priority and honestly? it's giving "I control the vibes of the whole scheduler". it's getpriority and setpriority, from the System Calls Manual, and I'm gonna hold your hand through every single line. no cap. 🫶

---

✨ NAME ✨

getpriority, setpriority — get/set program scheduling priority. that's it, that's the whole job, and they do it flawlessly. 👑

---

📚 LIBRARY 📚

Standard C library — the one and only libc, and you link it with -lc. she's always there for you. 💅

---

🎀 SYNOPSIS 🎀

#include <sys/resource.h>

int getpriority(int which, id_t who);
int setpriority(int which, id_t who, int prio);

look at those signatures. so clean. so crisp. main character energy fr. ✨

---

🌸 DESCRIPTION 🌸

So here's the tea, bestie: the scheduling priority of a process, a process group, or a user — whichever one you point at with which and who — gets obtained with the getpriority() call and set with the setpriority() call. and the process attribute these syscalls are messing with is literally the same attribute the whole time (aka the "nice" value) that nice(2) deals with. same vibe, different door. 🚪

The which argument is one of PRIO_PROCESS, PRIO_PGRP, or PRIO_USER, and who gets interpreted relative to which — like, it means a process identifier when which is PRIO_PROCESS, a process group identifier when it's PRIO_PGRP, and a user ID when it's PRIO_USER. and if you hand it a who of zero? it denotes, respectively, the calling process, the process group of the calling process, or the real user ID of the calling process. zero = "me, myself, and I" energy. 🙈

Now, the prio argument is a value in the range -20 to 19 (but pls see NOTES below, I'm not done with you yet), where -20 is the highest priority and 19 is the lowest priority. and if you try to set a priority outside that range? it gets silently clamped to the range. no error, no drama, just quietly corrected like a friend fixing your eyeliner. 🎀

The default priority is 0, and lower values give a process a higher scheduling priority. yes, it's backwards, yes, we've all accepted this, it's iconic in a cursed way. 💀

getpriority() returns the highest priority — that's the lowest numerical value — enjoyed by any of the specified processes. setpriority() sets the priorities of all of the specified processes to the specified value. periodt.

Traditionally, only a privileged process could lower the nice value (i.e., set a higher priority). However, since Linux 2.6.12, an unprivileged process can decrease the nice value of a target process that has a suitable RLIMIT_NICE soft limit — go read getrlimit(2) for the details, bestie. glow-up of the century tbh. ✨

---

🦋 RETURN VALUE 🦋

On success, getpriority() returns the calling thread's nice value, which may be a negative number. on error, it returns -1 and sets errno to indicate the error.

⚠️ okay this part is IMPORTANT, don't skip it: since a successful call to getpriority() can legitimately return the value -1, you have to clear errno prior to the call, then check errno afterward to figure out whether that -1 is an error or a legit value. it's giving "gaslight, gatekeep, girlboss" but for errno. 😭

setpriority() returns 0 on success. on failure, it returns -1 and sets errno to indicate the error. simple. flawless. no notes. 💅

---

💜 ERRORS 💜

• EACCES — the caller attempted to set a lower nice value (i.e., a higher process priority) but did not have the required privilege. on Linux: did not have the CAP_SYS_NICE capability. the audacity? denied. 🙅
• EINVAL — which was not one of PRIO_PROCESS, PRIO_PGRP, or PRIO_USER. you gave it a stranger and it said no. 💀
• EPERM — a process was located, but its effective user ID did not match either the effective or the real user ID of the caller, and it was not privileged (on Linux: did not have the CAP_SYS_NICE capability). but see HISTORY below. 👀
• ESRCH — no process was located using the which and who values you specified. ghosted. literally nobody home. 👻

---

🌈 STANDARDS 🌈

POSIX.1-2024. certified, stamped, respected. 👑

---

🧚 HISTORY 🧚

4.2BSD, SVr4, SUSv1, POSIX.1-2001 XSI. a whole lineage, a whole dynasty. 🫶

okay so the details on the condition for EPERM depend on the system. the description above is what POSIX.1-2001 says, and it seems to be followed on all System V-like systems. Linux kernels before Linux 2.6.12 required the real or effective user ID of the caller to match the real user of the process who — (instead of its effective user ID, bestie, read that again). Linux 2.6.12 and later require the effective user ID of the caller to match the real or effective user ID of the process who. and all BSD-like systems (SunOS 4.1.3, Ultrix 4.2, 4.3BSD, FreeBSD 4.3, OpenBSD-2.5, ...) behave in the same manner as Linux 2.6.12 and later. so basically everyone agreed except old Linux. ancient beef. 🍵

---

👑 NOTES 👑

for further details on the nice value, go see sched(7). it's the extended universe. 📖

Note: the addition of the "autogroup" feature in Linux 2.6.38 means that the nice value no longer has its traditional effect in many circumstances. for details, see sched(7). yes, this is real, yes, it changed everything, no, I'm not okay about it. 😭

a child created by fork(2) inherits its parent's nice value. and the nice value is preserved across execve(2). she survives the transformation. that's called resilience. ✨

🐚 C library/kernel differences 🐚

The getpriority system call returns nice values translated to the range 40..1, because a negative return value would be interpreted as an error — sneaky little workaround, we love a hack. 💅

The glibc wrapper function for getpriority() translates the value back according to the formula:

unice = 20 - knice

so the 40..1 range returned by the kernel corresponds to the range -20..19 as seen by user space. math? ate. 🍽️

---

💀 BUGS 💀

According to POSIX, the nice value is a per-process setting. However, under the current Linux/NPTL implementation of POSIX threads, the nice value is a per-thread attribute — meaning different threads in the same process can have different nice values. 😳

Portable applications should avoid relying on the Linux behavior, which may be made standards conformant in the future. so like… don't build your whole personality on it, bestie. 🙈

---

🌟 SEE ALSO 🌟

• nice(1)
• renice(1)
• fork(2)
• capabilities(7)
• sched(7)

and also: Documentation/scheduler/sched-nice-design.rst in the Linux kernel source tree (since Linux 2.6.23). deep lore for the scholars. 📚

---

and that's the whole page, bestie!! go forth and set your priorities (maybe not to -20, you're not that privileged, EACCES said no 💅). this was the getpriority(2) manual page from Linux man-pages 6.20, dated 2026-01-23 — that's the source, that's the version, that's the date, and that's the sign-off. mwah. 🎀💖✨🦋🌸