PTY(4) | Device Drivers Manual | PTY(4) |
pty
, ptm
—
pseudo terminal driver
pseudo-device pty
[count]
The pty
driver provides support for a
device-pair termed a
pseudo
terminal. A pseudo terminal is a pair of character devices, a
master
device and a
slave
device. The slave device provides to a process an interface identical to
that described in tty(4). However, whereas
all other devices which provide the interface described in
tty(4) have a hardware device of some sort
behind them, the slave device has, instead, another process manipulating it
through the master half of the pseudo terminal. That is, anything written on
the master device is given to the slave device as input and anything written
on the slave device is presented as input on the master device.
In configuring, if an optional count is given in the specification, space for that number of pseudo terminal pairs is preallocated. If the count is missing or is less than 2, a default count of 8 is used. This is not a hard limit--space for additional pseudo terminal pairs is allocated on demand up to the limit of 992.
The following ioctl(2) calls
apply only to pseudo terminals and may only be applied to the
pty
master:
TIOCEXT
int *onWhile external processing is enabled, input line editing, character echo, and mapping of control characters to signals are disabled regardless of the terminal's termios(4) settings.
TIOCSTOP
void^S
’).TIOCSTART
voidTIOCSTOP
or by typing
‘^S
’).TIOCPKT
int *onWhile packet mode is enabled, each subsequent
read(2) from the
pty
master will either return data written to
the pty
slave 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
TIOCPKT_FLUSHWRITE
TIOCPKT_STOP
^S
’.TIOCPKT_START
TIOCPKT_DOSTOP
^S
’ and
t_startc
is ‘^Q
’.TIOCPKT_NOSTOP
^S/^Q
’.TIOCPKT_IOCTL
Additionally, when the
TIOCPKT_IOCTL
bit is set, the remainder of
the data read from the pty
master is a copy
of the new termios(4)
structure.
While this mode is in use, the presence of control status information to be read from the master side may be detected by a select(2) for exceptional conditions.
TIOCUCNTL
int *onTIOCPKT
. The TIOCUCNTL
and
TIOCPKT
modes are mutually exclusive. This mode is
enabled from the master side of a pseudo terminal. Each subsequent
read(2) from the master side will return
data written on the slave part of the pseudo terminal preceded by a zero
byte, or a single byte reflecting a user control operation on the slave
side. A user control command consists of a special
ioctl(2) operation with no data; the
command is given as UIOCCMD
(n), where
n is a number in the range 1-255. The operation
value n will be received as a single byte on the
next read(2) from the master side. The
ioctl(2)
UIOCCMD
(0) is a no-op that may be used to probe
for the existence of this facility.
While this mode is in use, any of the
TIOCSBRK
and TIOCCBRK
ioctl requests issued on the slave part of the pseudo terminal will be
translated to a TIOCUCNTL_SBRK
or
TIOCUCNTL_CBRK
user command on the master
side.
As with TIOCPKT
mode, command
operations may be detected with a
select(2) for exceptional
conditions.
TIOCREMOTE
int *onTIOCPKT
. This mode causes input to the pseudo
terminal to be flow controlled and not input edited (regardless of the
terminal mode). Each write to the control terminal produces a record
boundary for the process reading the terminal. 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 end-of-file character.
TIOCREMOTE
can be used when doing remote line
editing in a window manager, or whenever flow controlled input is
required.The standard way to allocate pty
devices
is through openpty(3), a function which
internally uses a PTMGET
ioctl(2) call on the
/dev/ptm device. The PTMGET
command allocates a free pseudo terminal, changes its ownership to the
caller, revokes the access privileges for all previous users, opens the file
descriptors for the master and slave devices and returns them to the caller
in struct ptmget.
struct ptmget { int cfd; int sfd; char cn[16]; char sn[16]; };
The cfd and sfd fields are the file descriptors for the controlling and slave terminals. The cn and sn fields are the file names of the controlling and slave devices.
The pty
driver appeared in
4.2BSD. The /dev/ptm device
was added in OpenBSD 3.5.
The ptm device will only work on systems
where the /dev directory has been properly populated
with pty
device nodes following the naming
convention used in OpenBSD. Since
ptm impersonates the super user for some operations
it needs to perform to complete the allocation of a pseudo terminal, the
/dev directory must also be writeable by the super
user.
June 5, 2018 | OpenBSD-current |