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

s6
Software
skarnet.org

# The s6-svwait program

s6-svwait blocks until a collection of supervised services goes up, or down.

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

## Interface

         s6-svwait [ -U | -u | -D | -d | -r | -R ] [ -a | -o ] [ -t timeout ] servicedir...

s6-svwait monitors one or more service directories given as its arguments, waiting for a state (ready, up or down) to happen. If no service directories are listed, it immediately exits 0.

## 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-svwait 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-svwait 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-svwait will wait until the services are down.
- `-D` : really down. s6-svwait 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-svwait will wait until the services are down, then until they are up. If the `-o` option is given, it waits until all services are down and one service is up; otherwise it waits until all the services have restarted.
- `-R` : restart and ready.. s6-svwait will wait until the services are down, then until they are up and ready. If the `-o` option is given, it waits until all services are down and one service is up and ready; otherwise it waits until all the services have restarted and are ready.
- `-o` : or. s6-svwait will wait until one of the given services comes up or down.
- `-a` : and. s6-svwait 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-svwait will print a message to stderr and exit 99. By default, timeout is 0, which means no time limit.

## Notes

- s6-svwait should be given one or more service directories as arguments, not a scan directory. If you need to wait for a whole scan directory, give all its contents as arguments to s6-svwait.
- s6-svwait will only work on service directories that are already active, i.e. have an s6-supervise process running on them. It will not work on a service directory where s6-supervise has not been started yet.

## Internals

s6-svwait spawns a s6-ftrigrd child to listen to notifications sent by s6-supervise. It also checks `supervise/status` files to get the current service states, so it is immune to race conditions.