 |
» |
|
|
|
NAMEptm — STREAMS master pty (pseudo-terminal) driver SYNOPSIS#include <sys/stropts.h>
#include <sys/ptyio.h>
#include <sys/strtio.h>
int open("/dev/ptmx", O_RDWR); DESCRIPTIONA pseudo-terminal (pty) consists of a tightly-coupled pair of character
devices, called the master device and slave device.
The pty master and
slave device drivers work together to simulate a terminal connection where
the master provides a connection to the pseudo terminal server process and
the slave provides a terminal device special file access for the terminal
application processes, as depicted below:
----------------
| pty functions |
Application <--> |----------------| <--> Server
Processes | Slave | Master | Process
| (pts) | (ptm) |
---------------- The slave driver,
pts
with
ptem
(STREAMS pty emulation module)
and
ldterm
(STREAMS line discipline module)
pushed on top (not shown for simplicity), provides a terminal interface
as described in
termio(7).
Whereas devices that provide the terminal interface described in
termio(7)
have a hardware device behind them; in contrast, the slave device has another
process manipulating it through the master side of the pty.
Data written on the master device is given to the slave device as input and
data written on the slave device is presented as input on the master device. In order to use the STREAMS pty subsystem, a node for the
master pty driver
/dev/ptmx
and
N
number of slave pty devices must be installed (see
pts(7)
for details on slave pty).
There are no nodes in
the file system for each individual master device.
Rather, the master driver is set up as a STREAMS clone driver (see
clone(7))
with its major device number set to the major for the clone driver
and its minor device number set to the major for the
ptm
driver.
The master driver is opened using the
open()
system call with
/dev/ptmx
as the device file parameter.
The clone open finds the next available minor
number for the master device.
The master device is available only if it
and its corresponding slave device are not already opened.
Only one
open is allowed on a master device whereas multiple open are allowed on the
slave device.
When the master device is opened, the corresponding slave
device is automatically locked out (see
pts(7)
on how to unlock the slave and obtain the slave device name).
After both the master and slave have been opened, the user has two file
descriptors which represent the end points of a full duplex connection
composed of two streams.
These two streams are automatically connected
by the master and slave
devices when they are opened.
The user may then push the necessary modules
on the master and slave streams (e.g.,
ptem
and
ldterm,
on
pts
for terminal semantics,
and
pckt
on
ptm
for Packet Mode feature). The master and slave drivers pass all STREAMS messages to their adjacent
drivers.
Only the
M_FLUSH
message needs some special processing because the
read queue of the master is connected to the write queue of the slave
and vice versa.
Hence, the
FLUSHR
flag is changed to
FLUSHW
flag and
vice versa whenever a
M_FLUSH
message travels across the master-slave link.
When the master device is closed, an
M_HANGUP
message is sent
to the corresponding slave device which will render that slave device
unusable.
The process on the slave side gets the errno
ENXIO
when attempting a
write()
system call on the slave device but it will be able to
read any data remaining on the slave stream.
Finally, when all the
data have been read, the
read()
system call will return 0 (zero) indicating that the slave can
no longer be used.
On the last close of the slave device, a zero-length
M_DATA
message is
sent to the corresponding master device.
When the application on the
master side issues a
read()
or
getmsg()
system calls and a 0 is returned.
The user of the master device decides
whether to close the master device file which will dismantle
the streams on the master side.
If the master device remains opened,
the corresponding slave device can be opened and used again by another user. Unlike the slave device, the master device does not act like a terminal.
If
O_NDELAY
or
O_NONBLOCK
is set, a read on the master device returns
-1 with errno set to
EAGAIN
if no data is available, and a write returns -1 with errno set to
EAGAIN
if there is internal flow control on the stream. The master
ptm
driver supports the following
ioctl()
requests:
- ISPTM
Determines whether the file descriptor is that of an open master device.
On success, it returns the major and minor number (type dev_t) of the master
device which can be used to determine the name of the corresponding slave
device.
On failure, it returns -1 with errno set to
EINVAL.
ISPTM
on HP-UX can return valid device number with negative value.
For example,
with major number of the STREAMS pty master being 0x9c,
ICPTM
will return 0x9C000000 which is a negative number.
Therefore, it is
imperative that applications check for an explicit -1 instead of "< 0"
(less than 0) on the return value. ISPTM
is used by functions
grantpt(),
unlockpt(),
and
ptsname().
User applications normally do not need to invoke this ioctl.
The format of this ioctl is:
int ioctl(master_fd, ISPTM, 0) - UNLKPT
Unlocks the master and the corresponding slave devices.
On success, it returns 0.
On failure, it returns -1 with errno set to
EINVAL.
UNLKPT
is used by function
unlockpt().
User applications normally do not need to invoke this ioctl.
The format of this ioctl is:
int ioctl(master_fd, UNLKPT, 0) - TIOCREMOTE
This ioctl puts the STREAMS pty in and out of Remote Mode.
When Remote Mode is on,
input data will be flow-controlled and passed through
ldterm
without any input processing regardless of the terminal mode.
When the pty
master driver receives this ioctl, it will send an
M_CTL
message downstream to
ldterm
via
ptm,
pts,
and
ptem.
The command in the
M_CTL
message is set to
MC_NO_CANON
or
MC_DO_CANON
depending whether to turn on or off the Remote Mode.
The format of this ioctl is:
int ioctl(master_fd, TIOCREMOTE, argument) where the argument is set to 1 to turn on Remote Mode
and 0 to turn it off.
Remote Mode is normally used
when doing remote line editing in a window manager,
or whenever flow-controlled input is required.
Each write to the master device produces
a record boundary for the process reading the slave devices.
In normal usage,
a write of data is like the data typed as a line on the terminal; a
write of 0 (zero) bytes is like typing an
EOF
(End-of-File) character. - TIOCSIGNAL
This ioctl allows the master process to send a signal to the slave process.
The format of this ioctl is:
int ioctl(master_fd, TIOCSIGNAL, argument) where the argument is the signal number as defined in the header file
<sys/signal.h>.
For example the master process can
send an
SIGINT
signal to the slave process
by doing:
ioctl(master_fd, TIOCSIGNAL, SIGINT)
AUTHORptm
was developed by HP and OSF. FILES- /dev/ptmx
Streams pty master clone device - /dev/pts/N
Streams pty slave devices (0 <=
N
<
NSTRPTY),
where
NSTRPTY
is a kernel tunable parameter which can be changed via SAM.
SEE ALSOinsf(1M),
getmsg(2),
ioctl(2),
open(2),
read(2),
write(2),
grantpt(3C),
ptsname(3C),
unlockpt(3C),
clone(7),
ldterm(7),
pckt(7),
ptem(7),
pts(7),
streamio(7),
termio(7). |
Printable version
