GETPRIORITY(2)

💖 GETPRIORITY 💖

okay bestie, we're in the System Calls Manual section (that's section 2, iykyk) and today's main character is the getpriority / setpriority duo. they're siblings. they come as a pair. you literally cannot talk about one without the other, it's giving twin energy fr fr ✨

---

✨ NAME ✨

getpriority, setpriority — get/set program scheduling priority 🎀

---

📚 LIBRARY 📚

Standard C Library (that's libc, link it with -lc) 🫶

---

🦋 SYNOPSIS 🦋

okay so first you gotta invite the headers to the party:

#include <sys/time.h>
#include <sys/resource.h>

and then here's the actual function glow-ups:

int
getpriority(int which, int who);

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

---

💅 DESCRIPTION 💅

So here's the tea. Every process, process group, or user has a scheduling priority — basically how much the scheduler likes them and how fast they get picked. You read that priority with getpriority() and you set it with setpriority(). And you tell it whose priority you mean using which and who together, like a lil buddy system 💖

The which argument is exactly one of PRIO_PROCESS, PRIO_PGRP, or PRIO_USER — no substitutions, no vibes-based guessing, periodt.

And who gets interpreted relative to whatever which you picked:

• a process identifier if which is PRIO_PROCESS
• a process group identifier if which is PRIO_PGRP
• a user ID if which is PRIO_USER

And if you pass a zero value for who? That's the "me, myself, and I" move — it denotes the current process, process group, or user. slay 🙈

The prio argument is a value in the range -20 to 20. The default priority is 0. And listen closely because this is the part that trips everyone up: lower priorities cause more favorable scheduling. so -20 is like, VIP velvet rope treatment, and 20 is standing outside in the rain 💀

getpriority() returns the highest priority — which means the lowest numerical value — enjoyed by any of the specified processes. yes that's confusing, yes it's on purpose, we live here now 😭

setpriority() sets the priorities of all of the specified processes to the specified value.

⚠️ Only the super-user may lower priorities. like, actually lower them. don't try it, bestie, it will not go how you want.

---

🔥 RETURN VALUES 🔥

Here's the gotcha and I need you to internalize it: getpriority() can legitimately return the value -1. Not as an error. As a real answer. So you literally cannot tell "error" from "real value" just by looking at the return 😭

So the move is: clear the external variable errno before the call, then check it afterward to figure out if that -1 is an error or a legitimate value. That's it. That's the ritual. do it every single time, no cap 🙏

The setpriority() function returns the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error. nice and simple, we love a straightforward queen 👑

---

💀 ERRORS 💀

The getpriority() and setpriority() system calls will fail if:

• [ESRCH] — No process was located using the which and who values specified. you asked for someone and nobody showed up. ghosted fr 🫥
• [EINVAL] — The which argument was not one of PRIO_PROCESS, PRIO_PGRP, or PRIO_USER. you made up a category. that's not a thing. 🙈

In addition to the errors indicated above, setpriority() will fail if:

• [EPERM] — A process was located, but neither its effective nor real user ID matched the effective user ID of the caller. so the process exists, you just don't get to touch it. not yours, not your business 💅
• [EACCES] — A non super-user attempted to lower a process priority. you tried to jump the velvet rope without the super-user wristband. absolutely not. 🚫

---

🌈 SEE ALSO 🌈

• nice(1)
• fork(2)
• renice(8)

go read those next, they're all part of the same little priority cinematic universe 🎬

---

🎀 HISTORY 🎀

The getpriority() system call appeared in 4.2BSD. it's old. it's iconic. it has been here longer than most of us and it's still booked and busy ✨

---

okay that's the whole page bestie!! this one's from Debian, dated June 4, 1993 — yeah, 1993, this manual page is older than the internet's entire personality and it still ate 💖 go forth, clear that errno, and schedule responsibly. mwah 🫶👑