S6-SVSTAT(8)

📦 version 2.15.1.0, in nixpkgs unstable

💖 S6-SVSTAT(8) — the s6-svstat glow-up 💖

okay so bestie, this is a page from the System Manager's Manual, and it's literally about s6-svstat: the little icon that prints a short, human-readable or programmatically parsable summary of the state of a process monitored by s6-supervise(8). she's giving ✨status update✨ energy and honestly? obsessed.

✨ SYNOPSIS ✨

s6-svstat
          [-uwNrpest | -o up,wantedup,normallyup,ready,paused,pid,pgid,exitcode,signal,signum,updownsince,readysince,updownfor,readyfor]
          [-n] servicedir

🌸 DESCRIPTION 🌸

s6-svstat gives you the tea about the process being monitored at the service directory servicedir — that's your s6-service-directory(7), iykyk — and then it exits 0. bye bestie, love you, here's the info.

When s6-svstat is invoked with no options, or with only the -n option, it prints a human-readable summary of all the available info on the service. in that case, -n tells it to print a signal number (instead of a signal name) if the supervised process was killed by a signal. the summary includes the following data, no cap:

  • whether the process is up or down, and if it's up, the number of seconds that it has been up. 🕐
  • the process' pid, if it is up, or its last exit code or terminating signal, if it is down.
  • what its default state is, if it's different from its current state.
  • the number of seconds since it last changed states.
  • whether the service is ready (cf. s6-notifywhenup(7)) as notified by the daemon itself, and if it is, the number of seconds that it has been that way. a service reported as down and ready simply means it's ready to be brought up. a service is down and not ready when it's in the cleanup phase — i.e. the ./finish script is still being executed. main character cleanup arc fr.

When s6-svstat is invoked with one or several options other than -n, it outputs programmatically parsable info instead. the output is a series of space-separated values, one value per requested field. 💅 the valid options are as follows:

🎀 OPTIONS 🎀

  • -o fields — list the fields to print. fields is a list of comma-separated field names. the valid field names are the following:
    • up — prints true if the service is up and false if it is down.
    • wantedup — prints true if s6-supervise(8) is currently instructed to (re)start the service when it is down, and false if s6-supervise(8) is currently instructed to leave the service alone. 🫶
    • normallyup — prints true if the service is supposed to start when s6-supervise(8) starts (i.e. there's no ./down file), and false if it is not (i.e. there is a ./down file).
    • ready — prints true if the service is ready, and false if it is not. note that a service can be both down and ready: it simply means it's ready to be started (i.e. no ./finish script is currently running). to check for service readiness, you should give this option along with up: the service is ready iff s6-svstat -o up,ready prints true true. (the true true case will never happen if the service does not support readiness notification.) 💀
    • paused — prints true if the service is paused (i.e. the process is currently stopped) and false if it is not. it's a rare flag — you shouldn't normally need to use this option. 🙈
    • pid — prints the pid of the supervised process. if the service is currently down, -1 is printed instead.
    • pgid — prints the process group of the supervised process. if the service is currently down, prints the process group of the last living instance of the service.
    • exitcode — prints the exit code of the last execution of ./run. if the service is currently up, or the last ./run process was killed by a signal, -1 is printed instead.
    • signal — prints the name of the signal the last ./run process was killed with. if the service is currently up, or the last ./run process was not killed by a signal, NA is printed instead.
    • signum — prints the number of the signal the last ./run process was killed with. if the service is currently up, or the last ./run process was not killed by a signal, -1 is printed instead.
    • updownsince — prints a TAI64N[1] label representing the absolute date when the service last changed states. ⭐
    • readysince — prints a TAI64N[1] label representing the absolute date when the service last became ready. note that this can either mean "service readiness" (if the service is currently up and ready), or "down readiness", i.e. the last time when the service was down and ready to be started (if the service is not currently up and ready).
    • updownfor — prints the number of seconds that have elapsed since the service last changed states.
    • readyfor — prints the number of seconds that have elapsed since the service last became ready (or ready to be started if it's currently not up and ready).
  • -u — equivalent to -o up.
  • -w — equivalent to -o wantedup.
  • -N — equivalent to -o normallyup.
  • -r — equivalent to -o ready.
  • -p — equivalent to -o pid.
  • -g — equivalent to -o pgid.
  • -e — equivalent to -o exitcode.
  • -s — equivalent to -o signal.
  • -t — equivalent to -o updownfor.

🦋 EXIT STATUS 🦋

  • 0 — success. slay. 👑
  • 1 — s6-supervise(8) not running on servicedir. 😭
  • 100 — wrong usage.
  • 111 — system call failed. 💀

🌈 EXAMPLES 🌈

s6-svstat -o up,ready

or its equivalent, s6-svstat -ur, will print true true if the service is up and ready, true false if the service has been started but has not notified readiness yet, false true if it is down and can be started, and false false if it is down and there's a ./finish script running that needs to exit before the service can be restarted. the whole vibe check in four booleans, iconic.

s6-svstat -o pid,exitcode,signal

or its equivalent, s6-svstat -pes, will print 42 -1 NA if the service has been started and ./run's pid is 42; it will print -1 0 NA if the service is down and ./run last exited 0; it will print -1 -1 SIGTERM if the service is down and ./run was last killed by a SIGTERM — as can happen, for instance, when you down the service via a call to s6-svc -d. periodt. 🔥

🧚 SEE ALSO 🧚

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

[1] https://cr.yp.to/libtai/tai64.html

this man page is ported from the authoritative documentation at: https://skarnet.org/software/s6/s6-svstat.html — go read the og, she's that girl. 💜

💅 AUTHORS 💅

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

okay that's the whole page, bestie 🫶 and for the cute sign-off: this beauty ships with Debian, dated June 8, 2024, and it lives at S6-SVSTAT(8) in the System Manager's Manual section — go forth and stat your services, mwah 💖🌸

📦 where this page comes from