pty.7 (2010 09)

ManualsBrandsHP ManualsSoftwareHP-UX Manpages

pty(7) pty(7)

NAME

pty - pseudo-terminal driver

DESCRIPTION

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 application

processes an interface identical to that described in termio (7). Unlike all other devices that provide the

interface described in termio (7), the slave device does not have a hardware device behind it. Instead, it

has another process manipulating it through the master half of the pseudo terminal. Thus anything writ-

ten 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.

----------------

| pty functions |

Application <--> |----------------| <--> Server

Processes | Slave | Master | Process

| (pts) | (ptm) |

----------------

Open and Close Processing

The slave side of the

pty interprets opening or closing the master side as a modem connection or discon-

nection on a real terminal. Only one open to the master side of a pty is permitted. An attempt to open

an already open master side returns -1 and sets the external variable errno to [EBUSY]. An attempt to

open the master side of a pty that has a slave with an open ﬁle descriptor returns

-1 and sets errno to

[EBUSY]. The potential problem of

ptys being found busy at opens can be avoided by using the clone

open functionality discussed in the next section.

An attempt to open a nonexistent

pty returns -1 and sets errno to [ENXIO]. If O_NDELAY

is not

speciﬁed, opens on the slave side hang until the master side is opened. If

O_NDELAY

is speciﬁed, opens

on the slave side return error if the master side is closed. Any

ioctl() or write()

request made on

the slave side of a

pty after the master side is closed returns -1 and sets the external variable

errno to

[EIO]. A

read() request made on the slave side of a pty after the master side is closed returns 0 bytes.

Closing the master side of a pty sends a SIGHUP hangup signal to the tty process group number of the

corresponding slave side and ﬂushes pending input and output.

Clone Open

In typical

pty usage, there is no preference among pty pairs. Thus, it is useful to be able to issue a sin-

gle open() that internally opens any available pty. An open on /dev/ptym/clone

returns an open

ﬁle descriptor of a free master

pty device. If there are no free devices, the open returns

-1 and sets

errno to [EBUSY]. The name of the slave device corresponding to the opened master device can be

found through a ptsname() request.

Processing ioctl() Requests

By default, any

ioctl() request deﬁned by termio (7) is recognized by both the master and slave sides of

a pty. These ioctl() requests are processed by the pty driver as speciﬁed by termio (7). In addition,

the ioctl() requests deﬁned below are recognized by the master side of a pty. The slave side only

recognizes ioctl() requests deﬁned by termio (7). An ioctl() request made on the slave side of a

pty after the master side is closed returns -1 and sets the external variable errno to [EIO]. An

ioctl() request not recognized by the pty returns -1 and sets the external variable errno to [EIN-

VAL]. Note that some of the master-side-only ioctl() requests affect which ioctl() requests are

recognized by the master and slave side of the

pty. These master-side-only ioctl() requests also

affect the way recognized ioctl() requests, open() requests, and close() requests are processed by

the pty driver.

The following

ioctl() requests, deﬁned in <sys/ptyio.h>, apply only to the master side of pty:

TIOCSIGSEND

Cause a signal to be sent from the slave side of the pty to the current tty process group

of the slave side. The value of the parameter is taken to be the signal number sent. An

[EINVAL] error is returned and no signal is sent if the speciﬁed signal number does not

refer to a legitimate signal (see signal (5)). Note that this request allows the server pro-

cess to send signals to processes not owned by the same user ID.

TIOCTTY Enable or disable all termio processing by a pty. termio processing is enabled if the

int addressed by arg is nonzero and disabled if the int addressed by arg is zero. By

HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1

Summary of content (8 pages)

PAGE 1
pty(7) pty(7) NAME pty - pseudo-terminal driver DESCRIPTION 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 application processes an interface identical to that described in termio (7). Unlike all other devices that provide the interface described in termio (7), the slave device does not have a hardware device behind it.
PAGE 2
pty(7) pty(7) default, termio processing is enabled. termio processing refers to processing of input and output described by termio (7) (such as tab expansion), as well as the processing of the ioctl() requests described by termio (7). When disabled, all input and output data is passed through the pty without modification. Issuing a TIOCTTY ioctl() request flushes all data buffered in the pseudo terminal and releases any processes blocked waiting for data.
PAGE 3
pty(7) pty(7) the slave side. In normal usage, writing data is like typing the data as a line on a terminal; writing zero bytes is equivalent to typing an end-of-file character (that is, the EOF character as defined in termio (7)). The data read by the slave side is identical to the data written on the master side. Data written on the slave side and read on the master side with TIOCREMOTE enabled is still subject to the normal termio (7) processing.
PAGE 4
pty(7) pty(7) handshake is done automatically. Trapping occurs in two forms that are identified by the ioctl() requests that enable or disable them — TIOCTRAP and TIOCMONITOR. These two forms are distinguished by the types of requests they affect and by the capabilities they provide. Trapping open() and close() requests is enabled or disabled by TIOCTRAP. Trapping ioctl() requests not defined by termio (7) are enabled or disabled by TIOCTRAP.
PAGE 5
pty(7) pty(7) errno_error can be used to return an error for trapped slave pty open() requests. See the discussion of the TIOCSMODES ioctl() for further information on open error mode. return_value The success value (initialized to zero) returned by ioctl() on the slave side when errno_error is not set. When the ioctl() argument received on the slave side is not a pointer, its value is stored as four bytes retrievable with an ioctl() request to the master side equal to argget.
PAGE 6
pty(7) pty(7) trapping is enabled if the int addressed by arg is nonzero and disabled if the int addressed by arg is zero. By default, TIOCMONITOR trapping is disabled. TIOCMONITOR works in series with TIOCTTY; that is, the TIOCMONITOR trapping must be enabled and TIOCTTY must be enabled for termio ioctl() requests to be trapped by TIOCMONITOR. TIOCMONITOR trapping can be enabled or disabled regardless of the state of TIOCTTY.
PAGE 7
pty(7) pty(7) whose open() or ioctl() request is trapped. Signals are postponed if they would otherwise cause the process to jump to an installed signal handler. Signals are not postponed if they would otherwise cause the process to abort or if they are being ignored. When the server process completes the handshake by means of the TIOCREQSET ioctl() request, the process returns to the calling program and any pending signals are then acted upon.
PAGE 8
pty(7) pty(7) WARNINGS The slave side cannot indicate an end-of-file condition to the master side. When using TIOCREMOTE, a single write() request to the master side of greater than 256 bytes may result in multiple smaller records being read from the slave side instead of only one record. AUTHOR pty was developed by the University of California, Berkeley.