RTPRIO(2)

💅 RTPRIO(2) — the manual page, but make it cute 💅

okay so bestie, welcome to rtprio, rtprio_thread — literally the syscalls that let you examine or modify realtime or idle priority. Yes. We're playing with scheduling vibes today. Sit down, hydrate, and let's get into it. 🫶

---

📚 LIBRARY

Standard C Library (libc, -lc) — the classic. She's always there for you. 💖

---

✨ SYNOPSIS ✨

#include <sys/types.h>
#include <sys/rtprio.h>

int
rtprio(int function, pid_t pid, struct rtprio *rtp);

int
rtprio_thread(int function, lwpid_t lwpid, struct rtprio *rtp);

Look at those signatures. Gorgeous. Iconic. No notes. 👑

---

🦋 DESCRIPTION 🦋

So, the rtprio() system call is used to lookup or change the realtime or idle priority of a process — or of the calling thread, if you're feeling low-key about it. And rtprio_thread() is used to lookup or change the realtime or idle priority of a thread. That's the whole assignment. She's focused. 💅

The function argument is the "what are we even doing here" knob, and it specifies the operation to be performed:

• RTP_LOOKUP — bestie, we're just looking. 👀 Lookup the current priority.
• RTP_SET — we're changing it. Setting the priority. Main character move. ✨

For the rtprio() system call, the pid argument specifies the process to operate on — and 0 means the calling thread. (Yeah, she said process but then said 0 for thread. It's giving flexible. 🌸) When pid is non-zero, the system call reports the highest priority in the process, or sets all threads' priority in the process, depending on the value of the function argument. So it's either a gossip report or a full group-chat announcement, no in-between. 😭

For the rtprio_thread() system call, the lwpid specifies the thread to operate on, and 0 means the calling thread. Same energy, smaller target. 🎀

The *rtp argument is a pointer to a struct rtprio, which is used to specify the priority and priority type. And this structure — I'm obsessed — has the following form:

struct rtprio {
        u_short type;
        u_short prio;
};

Two little fields. Tiny. Powerful. The way that two u_shorts are carrying the entire scheduling destiny of a thread?? 💀

The value of the type field may be:

• RTP_PRIO_REALTIME — for realtime priorities. She's urgent. She's now. 🔥
• RTP_PRIO_NORMAL — for normal priorities. Just a girl. 🌈
• RTP_PRIO_IDLE — for idle priorities. Only when nothing else is happening. Respectfully. 🍓

The priority specified by the prio field ranges between 0 and RTP_PRIO_MAX (usually 31). And heads up — 0 is the highest possible priority. Yes, backwards from what your brain wants. Number go up, priority go down. That's just the lore. 🤷♀️

Realtime and idle priority is inherited through fork() and exec(). So it runs in the family. Generational priority, fr fr. 🧬

Okay and now the actual behavior, which is the juicy part:

• A realtime thread can only be preempted by a thread of equal or higher priority, or by an interrupt. Nothing else can touch her. 👑
• Idle priority threads will run only when no other real/normal priority thread is runnable. They're the "text me when you're free" friend. 🥺
• Higher real/idle priority threads preempt lower real/idle priority threads. Ranking matters. ⭐
• Threads of equal real/idle priority are run round-robin. Everybody gets a turn, we take turns in this house. 🫶

---

💖 RETURN VALUES 💖

The rtprio() and rtprio_thread() functions return the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error. So 0 = slay, -1 = check errno, bestie. 😭

---

🚨 ERRORS 🚨

The rtprio() and rtprio_thread() system calls will fail if:

• [EFAULT] — The rtp pointer passed to rtprio() or rtprio_thread() was invalid. Bad pointer, babe. She's not there. 💀
• [EINVAL] — The specified prio was out of range. You colored outside the lines. 🙈
• [EPERM] — The calling thread is not allowed to set the realtime priority. Listen: only root is allowed to change the realtime priority of any thread, and non-root may only change the idle priority of threads the user owns, when the sysctl(8) variable security.bsd.unprivileged_idprio is set to non-zero. So like, permissions are real. Do not test her. 🚫
• [ESRCH] — The specified process or thread was not found or visible. She's not in the group chat. Can't find her. 🔍

---

👀 SEE ALSO 👀

nice(1), ps(1), rtprio(1), setpriority(2), nice(3), renice(8), p_cansee(9)

Go read those too, bestie. Cross-referencing is self-care. 📚✨

---

🫶 AUTHORS 🫶

The original author was Henrik Vestergaard Draboel <hvd@terry.ping.dk>. This implementation in FreeBSD was substantially rewritten by David Greenman. The rtprio_thread() system call was implemented by David Xu. Legends, all of them. Thank you for your service. 🎀

---

And that's the page!! This one's from the Debian crew, dated December 27, 2011 — oldie but a goodie, and she still ate. 💅✨ Now go set some priorities (responsibly, as root, obviously). Byeee 🦋