THR_kill(2)

📦 version 12.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ THR_kill 💅 — bestie, we're sending signals to threads

okay so this is THR_kill(2), a page from the System Calls Manual, and it is genuinely one of my faves because it's SO direct about what it does. let's get into it 🫶

🌸 NAME 🌸

thr_kill — send signal to thread 💌

📚 LIBRARY 📚

Standard C Library (libc, -lc) — yeah she lives in libc, no cap

✨ SYNOPSIS ✨

#include <sys/thr.h>

int
thr_kill(long id, int sig);

int
thr_kill2(pid_t pid, long id, int sig);

look at her. two functions. both iconic. one of them lets you point at a different process, which is very main character energy of it 👑

💖 DESCRIPTION 💖

okay so the tea: thr_kill() and thr_kill2() are system calls that let you send a signal — that's the sig argument, bestie — to some threads in a process. not all of them necessarily, just the ones you pick. and yes you DO get to pick, we'll get there.

  • for thr_kill(), the threads you can signal are always limited to the current process. you stay in your lane, you signal your own people. 💅
  • for thr_kill2(), the pid argument is what specifies the process whose threads you wanna signal. so you can reach out to another process. bold. love that for you.

now the fun part — the id argument is literally the "who gets the signal" selector:

  • if id is equal to -1, all threads in the specified process are signalled. everyone. the whole group chat. 🎉
  • otherwise, only the thread whose thread identifier equals that argument gets signalled. just the one. targeted. precise. it's giving sniper but make it threads 🎯

and the sig argument defines the delivered signal. it must be a valid signal number, or zero. and zero is the sneaky one — when sig is zero, no signal is actually sent, and the call is used to verify the liveness of the thread. it's a vibe check fr fr. is this thread still alive? ask thr_kill with a zero and find out 🫣

oh and one more detail that matters: the signal is delivered with siginfo si_code set to SI_LWP. remember that, iykyk.

🔥 RETURN VALUES 🔥

if it goes well, thr_kill() and thr_kill2() return zero. slay. ✨

otherwise -1 is returned, and errno is set to indicate the error. so like, when it's bad, it tells you why. we love an honest king 😭

💀 ERRORS 💀

the thr_kill() and thr_kill2() operations return the following errors:

  • [EINVAL] — the sig argument is not zero and does not specify valid signal. bestie. that's not a signal. 🚫
  • [ESRCH] — the specified process or thread was not found. they're gone. ghosted. literally not there. 👻

additionally, thr_kill2() may return the following errors:

  • [EPERM] — the current process does not have sufficient privilege to check existence or send a signal to the specified process. so you tried to reach into somebody else's process and the kernel said no. permission check failed, babes. 🙈

🦋 SEE ALSO 🦋

the friend group 💕

🌈 STANDARDS 🌈

so the thr_kill() and thr_kill2() system calls are non-standard — not in the official standards club, they're doing their own thing — and they're used by the 1:1 Threading Library (libthr, -lthr) to implement IEEE Std 1003.1-2001 (“POSIX.1”) pthread(3) functionality.

basically they're the backstage crew making the whole pthread situation happen and nobody claps for them. not on my watch. 👏💜

🌟 heads up bestie: these are non-standard calls, so don't go assuming they exist on every system out there. they're a libthr thing. check your platform, fr fr.

and that's the page!! thr_kill and thr_kill2, sending signals to threads with surgical precision, since forever. this particular page is from the Debian edition and it's dated June 1, 2016 — vintage but still ate, no crumbs left. mwah 💅🎀✨

📦 where this page comes from