S6-SVLISTEN1(8)

📦 version 2.15.1.0, in nixpkgs unstable

🌸 NAME 🌸

Okay bestie, meet s6-svlisten1(8) — a tiny little program-runner that listens for notifications from a supervised service, and then blocks until that service goes up or down. It’s giving “I’m just here for the state change” energy. 💅

✨ SYNOPSIS ✨

s6-svlisten1 [-U | -u | -D | -d | -r | -R] [-t timeout] servicedir
             prog...

💫 DESCRIPTION 💫

Okay so the absolute main-character rule of s6-svlisten1 is this: it only waits for notifications, and it never polls. No polling, periodt. ✨

s6-svlisten1 checks the state of the servicedir (s6-service-directory(7)) and monitors its state changes. 👑

It spawns prog... as a child right after getting the initial state of the service. 🫶

Then it blocks until the wanted state happens. Literally just vibing until the state check says yes. 🦋

It’s the service-specific version of s6-ftrig-listen1(8). The whole point of s6-svlisten1 is to use it to spawn a program such as s6-svc(8), in order to send signals to a service while making sure to catch its state changes — thus avoiding the race condition that occurs when running s6-svc(8) then s6-svwait(8) sequentially. Race condition? Not on our watch, bestie. 💅

The s6-svlisten(8) program is an extension of s6-svlisten1. It can watch the state of several services at once; however, its syntax makes it best used in execline[1] scripts only. 🎀

🎀 OPTIONS 🎀

  • -u — Up. s6-svlisten1 will wait until the service is up, as reported by s6-supervise(8). This is the default; it is not reliable, but it does not depend on specific support in the service programs. See s6-notifywhenup(7) for details.
  • -U — Really up. s6-svlisten1 will wait until the service is up and ready as reported by the daemon itself. This requires specific support in the service programs, and the use of the notification-fd file in the s6-service-directory(7). See the explanation in s6-notifywhenup(7).
  • -d — Down. s6-svlisten1 will wait until the service is down.
  • -D — Really down. s6-svlisten1 will wait until the service is down and the cleanup script in servicedir/finish has finished executing (or has timed out and been killed).
  • -r — Restart. s6-svlisten1 will wait until the service has been started or restarted, i.e. they have been in the down state, then the up state.
  • -R — Restart and ready. s6-svlisten1 will wait until the service has been started or restarted and has notified readiness.
  • -t timeout — If the requested event has not happened after timeout milliseconds, s6-svlisten1 will print a message to stderr and exit 99. By default, timeout is 0, which means no time limit. ⏳

🦋 EXIT STATUS 🦋

  • 0 — Success, the wanted state has been reached. 🎉
  • 1 — The service was supposed to go up, but reported permanent failure. 😭
  • 99 — Timed out. 💀
  • 100 — Wrong usage. 🙈
  • 102 — The s6-supervise(8) process monitoring the service died. ⚰️
  • 111 — System call failed

🌈 SEE ALSO 🌈

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

This man page is ported from the authoritative documentation at: https://skarnet.org/software/s6/s6-svlisten1.html 🌸

👑 AUTHORS 👑

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

— source/version vibes: Debian, September 29, 2021, S6-SVLISTEN1(8) 🫶

📦 where this page comes from