S6-SVLISTEN(8)

💖 s6-svlisten — the manual, but make it make sense 💖

ok so this is a page from the System Manager's Manual, section 8 (that's the "admin commands" section bestie, iykyk). It's called s6-svlisten and honestly it's kind of a baddie once you get what it does.

---

✨ NAME ✨

s6-svlisten — run a program while listening on notifications from a whole collection of supervised services, and block until they all go up, or down 🎀

🌸 SYNOPSIS 🌸

ok so there's two ways to call her, depending on where you live:

• In an execline[1] script:

s6-svlisten [-U | -u | -D | -d | -r | -R] [-a | -o] [-t timeout]
            {servicedir servicedir...} prog...

• Outside of an execline script:

s6-svlisten [-U | -u | -D | -d | -r | -R] [-a | -o] [-t timeout]
            servicedir servicedir... "" prog...

notice the little "" in the second one? that's the vibe divider between the service dirs and your program, do not skip it 💅

🦋 DESCRIPTION 🦋

the way that s6-svlisten only waits for notifications — it literally never polls. not once. she's not out here refreshing the page, she's got notifications turned on and she's chilling. ✨

so what she does is: she checks the state of one or more s6-service-directory(7)s that you gave her as arguments in that first block, and then she monitors their state changes. 👑

she spawns prog... as a child right after getting the initial state of all the monitored services. then she blocks until the wanted state actually happens. periodt.

and if there are no service directories listed (the block is empty), then instead of doing all of that, she immediately exec(3)s into prog.... no waiting, no drama, just yeet. 💨

s6-svlisten is the service-specific version of s6-ftrig-listen(8). the whole point of her is to spawn a program like s6-svc(8) and send signals to services while making sure you catch their state changes — which avoids that nasty race condition you get when you run s6-svc(8) and then s6-svwait(8) one after the other. no cap, that's the entire reason she exists. 🫶

she needs to handle a variable length list of service directories, and for that she uses an encoding provided by execline — so it's genuinely best to only use her in execline scripts (only the execline syntax is guaranteed not to change, everyone else is on notice 💀). there's a variant, s6-svlisten1(8), that doesn't use execline syntax, but it only handles one service directory. tradeoffs, bestie.

⚠️ heads up: the -R or -r options imply the -a option. and it is not possible to wait for one of the listed services to restart. that's just not a thing she does. 🙈

💅 OPTIONS 💅

• -u — Up. she waits until the services are up, as reported by s6-supervise(8). this is the default; it's not reliable, but it doesn't depend on any specific support in the service programs. see s6-notifywhenup(7) for the details. lowkey the easy option, highkey the sketchy one. 😭
• -U — Really up. she waits until the services are up and ready, as reported by the services themselves. this one requires specific support in the service programs, and the use of the notification-fd file in the service directory. see the explanation in s6-notifywhenup(7). the trustworthy one. 👑
• -d — Down. she waits until the services are down. simple. iconic. 💜
• -D — Really down. she waits until the services are down and the cleanup scripts in servicedir/ finish for every servicedir have finished executing (or have timed out and been killed). yes, the original says "finish … have finished", we're keeping the energy. 💀
• -r — Restart. she waits until all the services have been started or restarted, i.e. they've been in the down state, and then the up state. 🌈
• -R — Restart and ready. she waits until all the services have been started or restarted and have notified readiness. ⭐
• -o — Or. she waits until one of the given services comes up or down. first one to pop off wins. 🔥
• -a — And. she waits until all of the given services come up or down. this is the default. everyone has to show up to the group chat. 🫶
• -t timeout — if the requested events haven't happened after timeout milliseconds, she prints a message to stderr and exits 99. by default timeout is 0, which means no time limit. no clock, no pressure. 🕐

😭 EXIT STATUS 😭

• 0 — success, the wanted state has been reached. slay. ✨
• 99 — timed out. she gave it a fair shot. 💀
• 100 — wrong usage. read the synopsis again bestie. 🙈
• 102 — the s6-supervise(8) process monitoring the service died. 😭
• 111 — system call failed. nothing to do with you, the kernel's just not cooperating. 🫠
• n — services were expected to come up, but n of them reported permanent failure. count the casualties. 💔

🧚 SEE ALSO 🧚

s6-notifyoncheck(8), s6-permafailon(8), s6-supervise(8), s6-svc(8), s6-svdt(8), s6-svdt-clear(8), s6-svlisten1(8), s6-svok(8), s6-svscan(8), s6-svscanctl(8), s6-svstat(8), s6-svwait(8)

[1] https://skarnet.org/software/execline/

this man page is ported from the authoritative documentation at: https://skarnet.org/software/s6/s6-svlisten.html

🎀 AUTHORS 🎀

Laurent Bercot Alexis <flexibeast@gmail.com> (man page port)

---

and that's the whole page babes 🫶 this version shipped with Debian, dated November 7, 2023, and the source/version line said s6-svlisten(8) all along — go forth and wait for notifications instead of polling like a civilian. 💖✨🌸