s6: the s6-svunlink program
Keywords: s6 command s6-svunlink supervision service stop unlink scandir servicedir

s6
Software
skarnet.org

# The s6-svunlink program

`s6-svunlink` unlinks a service directory from a scan directory, then notifies s6-svscan that a service has been unregistered. It waits until the s6-supervise supervisor process managing the service has disappeared, then exits.

The point of `s6-svunlink` is to help integrate service directories into an existing service manager sequence and eliminate race conditions.

## Interface

         s6-svunlink [ -X ] [ -t timeout ] scandir name

- `s6-svunlink` expects a running s6-svscan process on scandir and a fully functional supervised service on service directory in scandir`/`name, which must be a symbolic link to a real directory located somewhere else.
- It deletes the scandir`/`name symlink.
- It sends a command to s6-svscan to signal it that a service has disappeared.
- It waits for the s6-supervise process managing the service directory to exit.
- It exits 0.

## Exit codes

- 0: success
- 100: wrong usage
- 111: system call failed

## Options

- `-X` : don't wait. `s6-svunlink` will exit right away, without waiting for the supervisor to exit first.
- `-t timeout` : if the supervisor has not exited after timeout milliseconds, `s6-svunlink` will still exit. The default is 0, meaning no time limit.

## Notes

- Using `s6-svunlink` to stop services is a suboptimal pattern: starting and stopping supervisors is a heavier operation than just stopping services. The simpler, more efficient pattern is to simply perform s6-svc -dwD scandir`/`name, which only commands, and waits for, the death of the service, without impacting the supervisor. Nevertheless, for symmetry with s6-svlink, this program is provided.
- `s6-svunlink` is a destructor; as is, it returns 0 even in situations that are nominal failures. For instance, it returns 0 even if its timeout expires; the rationale is that there is no sensible action for the user to do if this error is reported. `s6-svunlink` only reports errors when they uncover a deeper problem in the system.
- `s6-svunlink` sends an s6-svscanctl -an command to scandir, which means that the system's view of services will be refreshed and inactive services will be killed and unsupervised. Depending on what links exist in scandir, new services may appear, and other services than name may disappear.