SIGIO_INIT(9)

💅 SIGIO_INIT(9) — the async IO signal API, explained by your favorite kernel gremlin

okay so this is a page from the Kernel Developer's Manual (yes, section 9, the cool section) and it's all about sigio_init, sigio_free, sigio_copy, sigio_setown, and sigio_getown — aka the asynchronous IO signal API. bestie, it's giving "who do I send this signal to" energy and honestly it ate. 🎀

---

✨ SYNOPSIS ✨

like, here's the whole cast, literally verbatim:

#include <sys/sigio.h>

void
sigio_init(struct sigio_ref *sir);

void
sigio_free(struct sigio_ref *sir);

void
sigio_copy(struct sigio_ref *dst, struct sigio_ref *src);

int
sigio_setown(struct sigio_ref *sir, u_long cmd, caddr_t data);

pid_t
sigio_getown(struct sigio_ref *sir, u_long cmd, caddr_t data);

look at them. five little functions. iconic. 👑

---

🌸 DESCRIPTION 🌸

so the asynchronous IO signal API provides a means to manage signal registrations. basically it associates a process or process group with a signal source — like setting them up on a little blind date, except the date gets automatically cancelled. and no cap: the association is revoked automatically when the process or process group is deleted. no lingering situationships. 🦋

now let me introduce each one:

• sigio_init() initializes the sigio reference sir. fresh start, clean slate, main character energy.
• sigio_free() clears any process or process group associated with reference sir. bye bestie 💅
• sigio_copy() copies the registration from reference src to reference dst. it's giving "you get what she has."
• sigio_setown() associates the reference sir with a process or process group. here's the tea: cmd is one of the ioctl commands FIOSETOWN, SIOCSPGRP, and TIOCSPGRP. and data is a pointer to a signed integer that represents the ID of the owner of the registration. so like, who's the owner? that's data's job to say.
  • for FIOSETOWN and SIOCSPGRP, a positive ID is taken as a process ID, and a negative ID is taken as a process group ID.
  • if cmd is TIOCSPGRP, a positive ID is taken as a process group ID, and negative ID values are not allowed. 🚫
  • for all values of cmd, the reference sir is cleared if the ID is zero. zero = nobody home.
• sigio_getown() stores the ID of the process or process group associated with the reference sir to the signed integer pointed by data. the cmd here is one of the ioctl commands FIOGETOWN, SIOCGPGRP, and TIOCGPGRP.
  • for FIOGETOWN and SIOCGPGRP, a process ID is stored as a positive ID, and a process group ID is stored as a negative ID.
  • for TIOCGPGRP, a process ID is stored as a negative ID, and a process group ID is stored as a positive ID. yes the signs flip, no I don't make the rules, that's just how it is 🙈
  • if there is no registered owner, a zero is stored in the integer. empty roster, as they say.

🫶 little certified-facts-only aside: when sigio_setown() is called, the invoking process' credentials are stored in the reference. these credentials are checked when the reference is used with pgsigio(9). so yeah, it remembers who did it. iykyk.

---

🧚 CONTEXT 🧚

sigio_init(), sigio_free(), sigio_copy(), sigio_setown() and sigio_getown() can be called during autoconf, or from process context. flexible queens. ✨

---

💀 RETURN VALUES 💀

sigio_setown() returns 0 on success. slay. otherwise, these error values come back at you:

• [EINVAL] — the process group ID is invalid.
• [EPERM] — the invoking process belongs to another session than the process or process group. not your session, not your problem 🔥
• [ESRCH] — the process or process group does not exist.
• [ESRCH] — the process is exiting. (yeah, same error, different reason, don't come for me 😭)

---

🌈 SEE ALSO 🌈

• pgsigio(9)

---

⭐ HISTORY ⭐

the sigio routines were adapted from FreeBSD and first appeared in OpenBSD 6.5. glow-up arc fr fr. 👑

---

and that's the whole page, bestie. no skips, no cuts, every flag and error intact. 🍓

🎀 this manual page is dated January 8, 2020, comes from Debian, and lives in section 9. mwah, go forth and register your signals responsibly. 💖