'\" te
.\" Copyright (c) 1994, Sun Microsystems, Inc.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.\" Copyright 2022 Oxide Computer Company
.Dd August 19, 2022
.Dt PTY 4D
.Os
.Sh NAME
.Nm pty
.Nd legacy pseudo-terminal driver
.Sh SYNOPSIS
.Pa /dev/pty[p-r]*
.Pp
.Pa /dev/tty[p-r]*
.Sh DESCRIPTION
This driver provides support for legacy static pseudo-terminal devices.
Modern software does not use this driver, preferring instead the STREAMS-based
.Xr ptm 4D
and
.Xr pts 4D
pseudo-terminal drivers, consumed through the portable
.Xr posix_openpt 3C
interface.
.Pp
The
.Nm pty
driver provides support for a pair of devices collectively known
as a
.Em pseudo-terminal .
The two devices comprising a pseudo-terminal are known as a
.Em manager
and a
.Em subsidiary .
The subsidiary device distinguishes between the
.Dv B0 baud rate and other baud rates specified in
the
.Fa c_cflag
field of the
.Vt termios
structure, and the
.Dv CLOCAL
flag in that member.
It does not support any of the other
.Xr termio 4I
device control functions specified by flags in the
.Fa c_cflag
field of the
.Vt termios
structure and by the
.Dv IGNBRK ,
.Dv IGNPAR ,
.Dv PARMRK ,
or
.Dv INPCK
flags in the
.Fa c_iflag
field of the
.Vt termios
structure, as these functions apply only to asynchronous serial ports.
All other
.Xr termio 4I
functions must be performed by STREAMS modules pushed atop the driver; when a
subsidiary device is opened, the
.Xr ldterm 4M
and
.Xr ttcompat 4M
STREAMS modules are automatically pushed on top of the stream, providing the
standard
.Xr termio 4I
interface.
.Pp
Instead of having a hardware interface and associated hardware that supports
the terminal functions, the functions are implemented by another process
manipulating the manager device of the pseudo-terminal.
.Pp
The manager and the subsidiary devices of the pseudo-terminal are tightly
connected.
Any data written on the manager device is given to the subsidiary device as
input, as though it had been received from a hardware interface.
Any data written on the subsidiary terminal can be read from the manager device
.Pq "rather than being transmitted from a UAR" .
.Pp
The driver is statically configured to provide 48 pseudo-terminal pairs.
Software that requires dynamic pseudo-terminal devices, or a greater number
of devices, must be converted to use
.Xr ptm 4D .
.Sh IOCTLS
The standard set of
.Xr termio 4I
ioctls are supported by the subsidiary device.
None of the bits in the
.Fa c_cflag
field have any effect on the pseudo-terminal, except that if the baud rate is
set to
.Dv B0 ,
it will appear to the process on the manager device as if the last process on
the subsidiary device had closed the line; thus, setting the baud rate to
.Dv B0
has the effect of
.Dq hanging up
the pseudo-terminal, just as it has the effect of
.Dq hanging up
a real terminal.
.Pp
There is no notion of
.Dq parity
on a pseudo-terminal, so none of the flags in the
.Fa c_iflag
field that control the processing of parity errors have any
effect.
Similarly, there is no notion of a
.Fa break ,
so none of the flags that control the processing of breaks, and none of the
ioctls that generate breaks, have any effect.
.Pp
Input flow control is automatically performed; a process that attempts to write
to the manager device will be blocked if too much unconsumed data is buffered
on the subsidiary device.
The input flow control provided by the
.Dv IXOFF
flag in the
.Fa c_iflag
field is not supported.
.Pp
The delays specified in the
.Fa c_oflag
field are not supported.
.Pp
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.
.Pp
A few special ioctls are provided on the manager devices of pseudo-terminals to
provide the functionality needed by applications programs to emulate real
hardware interfaces:
.Bl -tag -width Ds
.It Dv TIOCSTOP
The argument is ignored.
Output to the pseudo-terminal is suspended, as if a
.Sy STOP
character had been typed.
.It Dv TIOCSTART
The argument is ignored.
Output to the pseudo-terminal is restarted, as if a
.Sy START
character had been typed.
.It Dv TIOCPKT
The argument is a pointer to an
.Vt int .
If the value of the
.Vt int
is non-zero,
.Em packet
mode is enabled; if the value of the
.Vt int
is zero, packet mode is disabled.
When a pseudo-terminal is in packet mode, each subsequent
.Xr read 2
from the manager device will return data written on the subsidiary device
preceded by a zero byte
.Po
symbolically defined as
.Dv TIOCPKT_DATA
.Pc ,
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:
.Bl -tag -width Ds
.It Dv TIOCPKT_FLUSHREAD
Whenever the read queue for the terminal is flushed.
.It Dv TIOCPKT_FLUSHWRITE
Whenever the write queue for the terminal is flushed.
.It Dv TIOCPKT_STOP
Whenever output to the terminal is stopped using
.Sy ^S .
.It Dv TIOCPKT_START
Whenever output to the terminal is restarted.
.It Dv TIOCPKT_DOSTOP
Whenever
.Em XON/XOFF
flow control is enabled after being disabled; it is
considered
.Dq enabled
when the
.Dv IXON
flag in the
.Fa c_iflag
field is set, the
.Dv VSTOP
member of the
.Fa c_cc
array is
.Sy ^S
and the
.Dv VSTART
member of the
.Fa c_cc
array is
.Sy ^Q.
.It Dv TIOCPKT_NOSTOP
Whenever
.Em XON/XOFF
flow control is disabled after being enabled.
.El
.It Dv TIOCREMOTE
The argument is a pointer to an
.Vt int .
If the value of the
.Vt int
is non-zero,
.Em remote
mode is enabled; if the value of the
.Vt 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 subsidiary device of the
pseudo-terminal is flow controlled and not input edited (regardless of the mode
the subsidiary side of the pseudo-terminal).
.Pp
Each write to the manager device produces a record boundary for the process
reading the subsidiary 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
.Sy EOF
character.
Note: this means that a process writing to a pseudo-terminal manager in remote
mode must keep track of line boundaries, and write only one line at a time to
the manager.
.Pp
If, for example, it were to buffer up several newline characters and write them
to the manager with one
.Xr write 2 ,
it would appear to a process reading from the subsidiary as if a single line
containing several newline characters had been typed
.Po
as if, for example, a user had typed the literal next
.Pq Sy LNEXT
character before typing all but the last of those newline characters
.Pc .
Remote mode can be used when doing remote line editing in a window manager, or
whenever flow controlled input is required.
.El
.Sh FILES
.Bl -tag -width Pa
.It Pa /dev/pty[p-r][0-9a-f]
Pseudo-terminal manager devices.
.It Pa /dev/tty[p-r][0-9a-f]
Pseudo-terminal subsidiary devices.
.El
.Sh SEE ALSO
.Xr rlogin 1 ,
.Xr posix_openpt 3C ,
.Xr ptm 4D ,
.Xr termio 4I ,
.Xr ldterm 4M ,
.Xr ttcompat 4M ,
.Xr rlogind 8
.Sh NOTES
This is a legacy device and should not be used by new software.
.Pp
It is apparently not possible to send an
.Sy EOT
by writing zero bytes in
.Dv TIOCREMOTE
mode.