PTM(4D) Devices PTM(4D)

NAME

ptm, pts - STREAMS pseudo-terminal manager and subsidiary drivers

SYNOPSIS

/dev/ptmx

/dev/pts/*

DESCRIPTION

The pseudo-terminal subsystem simulates a terminal connection, where
the manager side represents the terminal and the subsidiary represents
the user process's special device end point. The manager device is set
up as a cloned device where its major device number is the major for
the clone device and its minor device number is the major for the ptm
driver; see CLONE_DEV in ddi_create_minor_node(9F).

There are no nodes in the file system for manager devices. The manager
pseudo driver is opened using the open(2) system call with /dev/ptmx as
the device parameter. The clone open finds the next available minor
device for the ptm major device.

A manager device is only available if it and its corresponding
subsidiary device are not already open. Only one open is allowed on a
manager device. Multiple opens are allowed on the subsidiary device.

When the manager device is opened, the corresponding subsidiary device
is automatically locked out. No user may open the subsidiary device
until its permissions are adjusted and the device is unlocked by
calling the functions grantpt(3C) and unlockpt(3C). The user can then
invoke the open(2) system call with the device name returned by the
ptsname(3C) function.

After both the manager and subsidiary have been opened, the user has
two file descriptors which are the end points of a full duplex
connection composed of two streams which are automatically connected at
the manager and subsidiary drivers. The user may then push modules
onto either side of the stream pair. Unless compiled in XPG4v2 mode
(see XPG4v2 MODE), the consumer needs to push the ptem(4M) and
ldterm(4M) modules onto the subsidiary device to get terminal
semantics.

The manager and subsidiary drivers pass all messages to their adjacent
queues. Only the M_FLUSH needs some processing. Because the read
queue of one side is connected to the write queue of the other, the
FLUSHR flag is changed to the FLUSHW flag and vice versa.

When the manager device is closed, an M_HANGUP message is sent to the
subsidiary device which will render the device unusable. The process
on the subsidiary side gets an EIO error when attempting to write on
that stream, but it will be able to read any data remaining on the
stream head read queue. When all the data has been read, read(2)
returns 0 indicating that the stream can no longer be used.

On the last close of the subsidiary device, a 0-length message is sent
to the manager device. When the application on the manager side issues
a read(2) or getmsg(2) and 0 is returned, the user of the manager
device decides whether to issue a close(2) that dismantles the entire
pseudo-terminal. If the manager device is not closed, the pseudo-
terminal will be available to another user to open the subsidiary
device.

Since 0-length messages are used to indicate that the process on the
subsidiary side has closed, and should be interpreted that way by the
process on the manager side, applications on the subsidiary side should
not write 0-length messages. Unless the application is compiled in
XPG4v2 mode (see XPG4v2 MODE), then any 0-length messages written to
the subsidiary device will be discarded by the ptem(4M) module.

If O_NONBLOCK or O_NDELAY is set on the manager side:

+o Read on the manager side returns -1 with errno set to EAGAIN if no
data is available

+o Write returns -1 with errno set to EAGAIN if there is internal flow
control

Standard STREAMS system calls can access pseudo-terminal devices. The
subsidiary devices support the O_NDELAY and O_NONBLOCK flags.

XPG4v2 MODE
XPG4v2 requires that subsidiary pseudo-terminal devices provide the
process with an interface that is identical to the terminal interface,
without needing to explicitly push any modules to achieve this. It
also requires that 0-length messages written on the subsidiary device
will be propagated to the manager device.

Experience has shown that most software does not expect subsidiary
pseudo-terminal devices to operate in this manner. This
XPG4v2-compliant behaviour is only enabled in XPG4v2/SUS (see
standards(7)) mode.

IOCTLS

The manager driver provides several ioctls to support the grantpt(3C),
unlockpt(3C), and ptsname(3C) functions:

ISPTM Determines whether the file descriptor is that of an open
manager device. On success, it returns the value 0.

UNLKPT Unlocks the manager and subsidiary devices. It returns 0 on
success. On failure, errno is set to EINVAL indicating that
the manager device is not open.

FILES

/dev/ptmx Pseudo-terminal manager clone device.

/dev/pts/N Pseudo-terminal subsidiary devices,
where N is a non-negative integer.
Located via calls to ptsname(3C).

EXAMPLES

Example 1 Opening the manager and subsidiary device for a pseudo-
terminal.

#include <stdlib.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>
#include <stropts.h>
#include <fcntl.h>
#include <err.h>
...
int fdm, fds;
char *subsidiaryname;
...
/*
* NOTE: Portable applications should use posix_openpt(3C) here:
*/
if ((fdm = open("/dev/ptmx", O_RDWR | O_NOCTTY)) < 0) {
err(1, "open manager");
}
if (grantpt(fdm) != 0 || unlockpt(fdm) != 0 ||
(subsidiaryname = ptsname(fdm)) == NULL) {
close(fdm);
err(1, "locate subsidiary");
}
if ((fds = open(subsidiaryname, O_RDWR | O_NOCTTY)) < 0) {
close(fdm);
err(1, "open subsidiary");
}
if (ioctl(fds, I_PUSH, "ptem") != 0 ||
ioctl(fds, I_PUSH, "ldterm") != 0) {
close(fds);
close(fdm);
err(1, "push modules");
}

SEE ALSO

close(2), getmsg(2), open(2), read(2), grantpt(3C), posix_openpt(3C),
ptsname(3C), unlockpt(3C), ldterm(4M), pckt(4M), ptem(4M),
standards(7), ddi_create_minor_node(9F)

illumos February 5, 2022 illumos