s6-linux-init: the s6-linux-init-telinit program

The `s6-linux-init-telinit` program

s6-linux-init-telinit changes runlevels, i.e. changes the system state. It is normally invoked as /sbin/telinit or just init with an argument.

Interface

     s6-linux-init-telinit rl

s6-linux-init-telinit may be called with the same options as s6-linux-init, but it ignores them all.
It calls the runleveld local service with the rl argument. This local service executes the user-provided runlevel script, which changes the system state to the state described by rl.
As a special case, if rl is 0 or 6, s6-linux-init-telinit then executes into s6-linux-init-hpr with the -p or -r option respectively, for compatibility with sysvinit's 0 and 6 runlevels that respectively halt and reboot the machine.

100: wrong usage
111: system call failed
Else, s6-linux-init-telinit exits with the same exit code as the runlevel script called with the rl argument.
If rl is 0 or 6, in case of success s6-linux-init-telinit exits 0, but the system shuts down immediately as it returns.

Traditional sysvinit only allows integer runlevels, from 0 to 6. More advanced service managers, like OpenRC or s6-rc, allow the admin to define alphanumerical runlevels, or states. s6-linux-init-telinit does not implement policy; it only makes sure the user-provided runlevel script is called with the rl argument, under a safe and reproducible environment. The runlevel script can then change the machine state as chosen by the user - typically by invoking the service manager.
The 0 and 6 special case has been added because some legacy programs may assume that calling init 0 and init 6 respectively halt and reboot the system.
The s6-linux-init-telinit binary is not meant to be called directly by administrators. Instead, after a s6-linux-init-maker invocation, the bin/ subdirectory of the target will contain a telinit symlink to s6-linux-init-telinit. The bin/ subdirectory should be copied by the administrator into /sbin for full interface compatibility with sysvinit.
When the system is running inside a container (and the -C option has been given to s6-linux-init-maker), the runleveld service is not running, so s6-linux-init-telinit is not functional and the runlevel script is never invoked.