Manual page for PTY(4)
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.
Created by unroff & hp-tools.
© somebody (See intro for details). All Rights Reserved.
Last modified 11/5/97