pty-run 1 user commands nosh
pty-run run a program under a pseudo-terminal
`pty-run` -t next-prog

## Description

`pty-run` is a utility that expects file descriptor 4 to be the back end (called "master side" in older documentation) of a pseudo-terminal and the `TTY` environment variable to be the full device filename of the front end. (pty-allocate 1 can be used to set this process state up.)

It spawns next-prog, closing the back-end file descriptor in the child process, and then enters a loop where it simultaneously:

- writes all data received from the back end to its own standard output, until the back end signals hangup (i.e. when the line discipline would set modem control lines, as it would on a real serial device, to signal hangup because the last front-end file descriptor is closed);

- writes all data received from its standard input to the back end, until its standard input signals EOF with a 0 byte read; and

- acts upon state changes in the spawned child process.

It has two modes:

- If the -t option was used, it behaves in "pass-through TTY" mode.

  It copies the terminal mode settings from its standard input or output to the pseudo-terminal and sets both its standard input and output to "raw" mode. If the child process stops with a stop signal, it undoes this and stops itself. When it receives a `SIGCONT`, it re-does it and sends a `SIGCONT` to its child.

- In the default if the -t option is not used, it behaves in "pipe" mode.

  It makes no alteration to terminal mode settings. If the child process stops with a stop signal, it simply sends it a `SIGCONT` immediately.

next-prog may contain its own command line options, which `pty-run` will ignore.

## Security

`pty-run` does not touch the front-end device at all. The front-end device race condition that must be avoided for open-controlling-terminal 1 (q.v.) and similar front-end programs should have already been handled by whatever created the pseudo-terminal (e.g. pty-allocate 1).

## See also

console-terminal-emulator 1

  an I/O pump that pumps data in both directions between the back end of a pseudo-terminal and an abstraction of a virtual terminal's display and human input device hardwares

## Author

Jonathan de Boyne Pollard