S6-SVLISTEN(8)

NAME
s6-svlisten - run a program while listening on notifications from a collection of supervised services, and block until they all go up, or down

SYNOPSIS

•   In an execline[1] 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...

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

s6-svlisten checks the state of one or more s6-service-directory(7)s given as arguments in the first block and monitors 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 exec(3) s into prog....

s6-svlisten is the service-specific version of s6-ftrig-listen(8). The point of s6-svlisten is to use it to spawn a program such as s6-svc(8), 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(8) then s6-svwait(8) 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(8).

The -R or -r options imply the -a option. It is not possible to wait for one of the listed services to restart.

OPTIONS

-u  Up. s6-svlisten will wait until the services are up, as reported by s6-supervise(8). This is the default; it is not reliable, but it does not depend on specific support in the service programs. See s6-notifywhenup(7) 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 in s6-notifywhenup(7).

-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 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.

EXIT STATUS

0   Success, the wanted state has been reached.

99  Timed out.

100 Wrong usage.

102 The s6-supervise(8) process monitoring the service died.

111 System call failed.

n   Services were expected to come up, but n of them reported permanent failure.

SEE ALSO
s6-notifyoncheck(8), s6-permafailon(8), s6-supervise(8), s6-svc(8), s6-svdt(8), s6-svdt-clear(8), s6-svlisten1(8), s6-svok(8), s6-svscan(8), s6-svscanctl(8), s6-svstat(8), s6-svwait(8)

[1] https://skarnet.org/software/execline/

This man page is ported from the authoritative documentation at: https://skarnet.org/software/s6/s6-svlisten.html

AUTHORS
Laurent Bercot Alexis <flexibeast@gmail.com> (man page port)