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
While 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
^S
’). Takes no parameter.TIOCSTART
TIOCSTOP
or by typing
‘^S
’). Takes no parameter.TIOCPKT
While 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
TIOCPKT
. The TIOCUCNTL
and
TIOCPKT
modes are mutually exclusive. This mode is
enabled from the master side of a pseudo terminal by specifying (by
reference) a nonzero parameter and disabled by specifying (by reference) a
zero parameter. 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. As with
TIOCPKT
mode, command operations may be detected
with a select(2) for
exceptional conditions.TIOCREMOTE
TIOCPKT
. 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 30, 2016 | OpenBSD-6.2 |