PTY(4)

NAME
pty - pseudo-terminal driver

CONFIG
pseudo-device ptyn

SYNOPSIS
#include <fcntl.h>
#include <sys/termios.h>
open("/dev/ttypn", mode);
open("/dev/ptypn", mode);

DESCRIPTION

The pty driver provides support for a pair of devices collectively known as a pseudo-terminal. The two devices comprising a pseudo-terminal are known as a controller and a slave. The slave device distinguishes between the B0 baud rate and other baud rates specified in the c_cflag word of the termios structure, and the CLOCAL flag in that word. It does not support any of the other termio(4) device control functions specified by flags in the c_cflag word of the termios structure and by the IGNBRK, IGNPAR, PARMRK, or INPCK flags in the c_iflag word of the termios structure, as these functions apply only to asynchronous serial ports. All other termio(4) functions must be performed by STREAMS modules pushed atop the driver; when a slave device is opened, the ldterm(4M) and ttcompat(4M) STREAMS modules are automatically pushed on top of the stream, providing the standard termio(4) interface.

Instead of having a hardware interface and associated hardware that supports the terminal functions, the functions are implemented by another process manipulating the controller device of the pseudo-terminal.

The controller and the slave devices of the pseudo-terminal are tightly connected. Any data written on the controller device is given to the slave device as input, as though it had been received from a hardware interface. Any data written on the slave terminal can be read from the controller device (rather than being transmitted from a UART).

In configuring, if no optional ``count'' is given in the specification, 16 pseudo-terminal pairs are configured.

IOCTLS
The standard set of termio ioctls are supported by the slave device. None of the bits in the c_cflag word have any effect on the pseudo-terminal, except that if the baud rate is set to B0, it will appear to the process on the controller device as if the last process on the slave device had closed the line; thus, setting the baud rate to B0 has the effect of ``hanging up'' the pseudo-terminal, just as it has the effect of ``hanging up'' a real terminal.

There is no notion of ``parity'' on a pseudo-terminal, so none of the flags in the c_iflag word that control the processing of parity errors have any effect. Similarly, there is no notion of a ``break'', so none of the flags that control the processing of breaks, and none of the ioctls that generate breaks, have any effect.

Input flow control is automatically performed; a process that attempts to write to the controller device will be blocked if too much unconsumed data is buffered on the slave device. The input flow control provided by the IXOFF flag in the c_iflag word is not supported.

The delays specified in the c_oflag word are not supported.

As there are no modems involved in a pseudo-terminal, the ioctls that return or alter the state of modem control lines are silently ignored.

On Sun systems, an additional ioctl is provided:

TIOCCONS
    The argument is ignored. All output that would normally be sent to the console (either from programs writing to /dev/console or from kernel printouts) is redirected so that it is written to the pseudo-terminal instead.

A few special ioctls are provided on the controller devices of pseudo-terminals to provide the functionality needed by applications programs to emulate real hardware interfaces:

TIOCSTOP
    The argument is ignored. Output to the pseudo-terminal is suspended, as if a STOP character had been typed.

TIOCSTART
    The argument is ignored. Output to the pseudo-terminal is restarted, as if a START character had been typed.

TIOCPKT
    The argument is a pointer to an int. If the value of the int is non-zero, packet mode is enabled; if the value of the int is zero, packet mode is disabled. When a pseudo-terminal is in packet mode, each subsequent read(2V) from the controller device will return data written on the slave device preceded by a zero byte (symbolically defined as TIOCPKT_DATA), or a single byte reflecting control status information. In the latter case, the byte is an inclusive-or of zero or more of the bits:

    TIOCPKT_FLUSHREAD
        whenever the read queue for the terminal is flushed.

    TIOCPKT_FLUSHWRITE
        whenever the write queue for the terminal is flushed.

    TIOCPKT_STOP
        whenever output to the terminal is stopped using ^S.

    TIOCPKT_START
        whenever output to the terminal is restarted.

    TIOCPKT_DOSTOP
        whenever XON/XOFF flow control is enabled after being disabled; it is considered ``enabled'' when the IXON flag in the c_iflag word is set, the VSTOP member of the c_cc array is ^S and the VSTART member of the c_cc array is ^Q.

    TIOCPKT_NOSTOP
        whenever XON/XOFF flow control is disabled after being enabled.

    This mode is used by rlogin(1C) and rlogind(8C) to implement a remote-echoed, locally ^S/^Q flow-controlled remote login with proper back-flushing of output when interrupts occur; it can be used by other similar programs.

TIOCREMOTE
    The argument is a pointer to an int. If the value of the int is non-zero, remote mode is enabled; if the value of the int is zero, remote mode is disabled. This mode can be enabled or disabled independently of packet mode. When a pseudo-terminal is in remote mode, input to the slave device of the pseudo-terminal is flow controlled and not input edited (regardless of the mode the slave side of the pseudo-terminal). Each write to the controller device produces a record boundary for the process reading the slave device. In normal usage, a write of data is like the data typed as a line on the terminal; a write of 0 bytes is like typing an EOF character. Note: this means that a process writing to a pseudo-terminal controller in remote mode must keep track of line boundaries, and write only one line at a time to the controller. If, for example, it were to buffer up several NEWLINE characters and write them to the controller with one write(), it would appear to a process reading from the slave as if a single line containing several NEWLINE characters had been typed (as if, for example, a user had typed the LNEXT character before typing all but the last of those NEWLINE characters). Remote mode can be used when doing remote line editing in a window manager, or whenever flow controlled input is required.

The ioctls TIOCGWINSZ, TIOCSWINSZ, and, on Sun systems, TIOCCONS, can be performed on the controller device of a pseudo-terminal; they have the same effect as when performed on the slave device.

FILES
/dev/pty[p-s][0-9a-f]
    pseudo-terminal controller devices
/dev/tty[p-s][0-9a-f]
    pseudo-terminal slave devices
/dev/console

SEE ALSO
rlogin(1C), termio(4), ldterm(4M), ttcompat(4M), rlogind(8C)

BUGS
It is apparently not possible to send an EOT by writing zero bytes in TIOCREMOTE mode.