ttyrun - start a program if a specified terminal device is available

As of s390-tools 1.9 (kernel 2.6.34), the ttyrun program can run on target systems to start a program on a terminal device; for example, a getty program.

ttyrun is typically started during the system startup procedures and is used to prevent a respawn through the system startup procedures when a terminal is not available.

Format


ttyrun syntax

>>-ttyrun--+-----+--+--------------+-- <term>-- <prog>--+-----------------+-><
           '- -V-'  '- -e <status>-'                    '- <prog_options>-'

where:

-V or --verbose

displays syslog messages.

-e <status> or --exitstatus <status>

specifies an exit status that is returned when the terminal device is not available. The exit status must be an integer in the range 1 - 255.

You can use this status value in an Upstart job file to prevent respawning.

With the -e option, ttyrun exits with the specified return value.
Without the -e option, ttyrun sleeps until it receives a signal that causes an exit.

<term>

specifies the name of the terminal device and is a path relative to the /dev directory; for example, specify hvc0 for /dev/hvc0. If the specified terminal device can be opened, ttyrun starts the specified program.

<prog>

specifies an absolute path to the program to be started by ttyrun.

<prog_options>

specifies arguments for the program to be started by ttyrun. Depending on the program, some arguments might be required. In the arguments, you can use %t as a variable that resolves to the specified terminal device.

-v or --version

displays the version number of ttyrun and exits.

-h or --help

displays a short help text and exits. For more detail, see the ttyrun man page.

ttyrun return values

ttyrun exits with one of the following return values to report an error condition:

1: ttyrun was called with an argument that is not valid or required but missing.
2: the <term> variable specifies a device that is not a terminal device.
3: ttyrun failed to start the specified program.

Do not inadvertently override these return values with the -e option.

4 - 255: The terminal device is not available and the -e option specifies an exit status in this range.

systemd example

Enable a getty service for hvc1 by issuing a command of this form:
```
# systemctl enable ttyrun-getty@hvc1.service
```
At the next system start, systemd starts the ttyrun service for hvc1. The ttyrun service starts a getty only if this terminal is available.
To start the service without a system restart, issue:
```
# systemctl start ttyrun-getty@hvc1.service
```

inittab example

This inittab entry starts /sbin/agetty on terminal device hvc1, if available:
```
h1:2345:respawn:/sbin/ttyrun hvc1 /sbin/agetty -L 9600 %t linux
```
ttyrun prevents the agetty program from respawning if hvc1 is not available.

Upstart example

An Upstart job file with the following content starts /sbin/agetty on terminal device hvc1, if available:
```
respawn
normal exit 42
exec /sbin/ttyrun -e 42 hvc1 /sbin/agetty -L 9600 %t linux
```
With the normal exit statement, you specify an exit status that prevents Upstart from respawning the program. To prevent respawning with ttyrun, you must specify the same value for the -e option and for the exit status. The example uses 42.