S6-SVLISTEN1(8)

NAME
s6-svlisten1 - run a program while listening on notifications from a supervised service, and block until said service goes up, or down

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

DESCRIPTION
s6-svlisten1 only waits for notifications; it never polls. s6-svlisten1 checks the state of the servicedir s6-service-directory(7) and monitors 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.

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

The s6-svlisten(8) 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[1] scripts only.

OPTIONS

-u  Up. s6-svlisten1 will wait until the service is 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-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 s6-service-directory(7). See the explanation in s6-notifywhenup(7).

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

EXIT STATUS

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(8) process monitoring the service died.

111 System call failed

SEE ALSO
s6-notifyoncheck(8), s6-permafailon(8), s6-supervise(8), s6-svc(8), s6-svdt(8), s6-svdt-clear(8), s6-svlisten(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-svlisten1.html

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