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.