s6
Software
skarnet.org

The s6-svlisten1 program

s6-svlisten1 runs a program while listening on notifications from a supervised service, and blocks until said service goes up, or down.

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

Interface

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

• s6-svlisten1 checks the state of the servicedir service directory and monitor its state changes.
• It spawns prog... as a child right after getting the initial state of the service.
• It then blocks until the wanted state happens.

Exit codes

• 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 process monitoring the service died
• 111: system call failed

Options

• -u : up. s6-svlisten1 will wait until the service is 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-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 service directory. See the explanation on this page.
• -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.

Notes

• s6-svlisten1 is the service-specific version of s6-ftrig-listen1. The point of s6-svlisten1 is to use it to spawn a program such as s6-svc, 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 then s6-svwait sequentially.
• The s6-svlisten 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 scripts only.