s6
Software
skarnet.org

The s6-svlisten program

s6-svlisten runs a program while listening on notifications from a collection of supervised services, and blocks until they all go up, or down.

s6-svlisten only waits for notifications; it never polls.

Interface

In an execline 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...

• s6-svlisten checks the state of one or more service directories given as arguments in the first block and monitor their state changes.
• It spawns prog... as a child right after getting the initial state of all the monitored services.
• It then blocks until the wanted state happens.
• If no service directories are listed (the block is empty), then instead of doing all that, it immediately execs into prog....

Exit codes

• 0: success, the wanted state has been reached
• 99: timed out
• 100: wrong usage
• 102: the s6-supervise process monitoring the service died
• 111: system call failed
• n: services were expected to come up, but n of them reported permanent failure

Options

• -u : up. s6-svlisten will wait until the services are up, as reported by s6-supervise. This is the default; it is not reliable, but it does not depend on specific support in the service programs. See this page for details.
• -U : really up. s6-svlisten will wait until the services are up and ready as reported by the services themselves. This requires specific support in the service programs, and the use of the notification-fd file in the service directory. See the explanation on this page.
• -d : down. s6-svlisten will wait until the services are down.
• -D : really down. s6-svlisten will wait 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).
• -r : restart. s6-svlisten will wait until all the services have been started or restarted, i.e. they have been in the down state, then the up state.
• -R : restart and ready. s6-svlisten will wait until all the services have been started or restarted and have notified readiness.
• -o : or. s6-svlisten will wait until one of the given services comes up or down.
• -a : and. s6-svlisten will wait until all of the given services come up or down. This is the default.
• -t timeout : if the requested events have not happened after timeout milliseconds, s6-svlisten will print a message to stderr and exit 99. By default, timeout is 0, which means no time limit.

Notes

• s6-svlisten is the service-specific version of s6-ftrig-listen. The point of s6-svlisten is to use it to spawn a program such as s6-svc, in order to send signals to services while making sure to catch their state changes - thus avoiding the race condition that occurs when running s6-svc then s6-svwait sequentially.
• s6-svlisten needs to handle a variable length list of service directories. For that, it uses an encoding provided by execline, so it's best to only use it in execline scripts (only the execline syntax is guaranteed not to change). There is a variant of s6-svlisten that does not use execline syntax, but only handles one service directory: s6-svlisten1.
• The -R or -r options imply the -a option. It is not possible to wait for one of the listed services to restart.