s6: the s6-svlisten1 program
Keywords: s6 command s6-svlisten1 notification service waiting

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.