Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > P

pty(7)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

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

---------------- | 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 disconnection 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 file 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 specified, opens on the slave side hang until the master side is opened. If O_NDELAY is specified, 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 flushes 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 single open() that internally opens any available pty. An open on /dev/ptym/clone returns an open file 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 defined 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 specified by termio(7). In addition, the ioctl() requests defined below are recognized by the master side of a pty. The slave side only recognizes ioctl() requests defined 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 EINVAL. 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, defined 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 specified signal number does not refer to a legitimate signal (see signal(5)). Note that this request allows the server process 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 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. Enabling and disabling TIOCTTY affects the operation of the following ioctl() requests: TIOCPKT, TIOCREMOTE, TIOCBREAK, TIOCSTOP, TIOCSTART, TIOCTRAP, and TIOCMONITOR.

When TIOCTTY is enabled, all termio ioctl() requests execute as specified in termio(7), regardless of the side from which the ioctl() request is made. When TIOCTTY is disabled, master side termio ioctl() requests set and return the the external variable errno to EINVAL. Slave side termio ioctl() requests are processed like any other ioctl() request when TIOCTTY is disabled. In particular, slave side termio ioctl() requests set and return the external variable errno to EINVAL when both TIOCTTY and TIOCTRAP are disabled. (See the discussion of ioctl(), open(), and close() trapping below). ioctl() requests not defined by termio(7) are not affected by the state of TIOCTTY.

Data written through a pseudo terminal with TIOCTTY disabled is handled in a manner similar to data flowing through a pipe. A write request blocks in the pty until all data has been written into the pty. A read request blocks if there is no data available unless the O_NDELAY flag is set (see fcntl(2)). When data is available to be read, the read request returns whatever is available, and does not wait for the number of bytes requested to be satisfied. The number of bytes a pty can contain in its internal memory is implementation dependent, but is at least 256 bytes in each direction. For example, a write on the slave side of a pty of 1024 bytes might be read on the master side by four read requests returning 256 bytes each. The size of the chunks of data that are read is not guaranteed to be consistent, but no data is lost.

The following ioctl() requests, defined in <sys/ptyio.h>, apply only to the master side of a pty. In particular, these ioctl() requests enable/disable specific modes of pty driver operation. These ioctl() requests work in series with TIOCTTY; that is, the mode must be enabled by its ioctl() request and TIOCTTY must be enabled for the mode to operate. The mode can be enabled or disabled regardless of the state of TIOCTTY.

TIOCPKT

Enable or disable packet mode. Packet mode is enabled if the int addressed by arg is nonzero and disabled if the int addressed by arg is zero. By default, packet mode is disabled. When applied to the master side of a pseudo terminal, each subsequent read() from the master side returns data written on the slave part of the pseudo terminal preceded by a zero byte (symbolically defined as TIOCPKT_DATA), or a single byte reflecting control status information. The value of such a status byte is composed of zero or more bit flags:

TIOCPKT_FLUSHREAD

The read queue for the slave side has been flushed.

TIOCPKT_FLUSHWRITE

The write queue for the slave side has been flushed.

TIOCPKT_STOP

Data flowing from the slave side of the pty to the master side has been stopped by means of ^S, TIOCSTOP, or TCXONC.

TIOCPKT_START

Data flowing from the slave side of the pty to the master side has been restarted.

TIOCPKT_DOSTOP

Stop and start characters have been set to ^S or ^Q.

TIOCPKT_NOSTOP

Stop and start characters are set to something other than ^S or ^Q.

TIOCREMOTE

Enable or disable remote mode. Remote mode is enabled if the int value of arg is nonzero and disabled if the int value of arg is zero. By default, remote mode is disabled. Remote mode is independent of packet mode. 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 master side produces a record boundary for the process reading 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. TIOCREMOTE can be used when doing remote line editing in a window manager, or whenever flow-controlled input is required. Issuing a TIOCMONITOR ioctl() request flushes all data buffered in the pseudo terminal.

The following ioctl() requests, defined in <sys/ptyio.h>, apply only to the master side of pty. In particular, these ioctl() requests are only recognized when TIOCTTY is enabled. When TIOCTTY is disabled, these ioctl() requests set and return the external variable errno to EINVAL.

TIOCBREAK

Cause a break operation to be done on the slave side of the pty, as if a user had pressed the break key on a real terminal. Takes no parameter.

TIOCSTOP

Stop data flowing from the slave side of the pty to the master side (equivalent to typing ^S). Takes no parameter.

TIOCSTART

Restart output (stopped by TIOCSTOP or by typing ^S). Takes no parameter.

Flow-Control Input and Output Processing

The following terms are used to describe the flow of data through pseudo terminals. INPUT refers to data flowing from the master side of a pty to the slave side. OUTPUT refers to data flowing from the slave side of a pty to the master side.

When packet mode (TIOCPKT) is disabled and INPUT is stopped (see IXOFF, input modes, in termio(7)), the next read() from the master side of a pty returns a STOP character. When INPUT is restarted, the next read() from the master side returns a START character. If packet mode (TIOCPKT) is enabled, the STOP or START character is preceded by a data packet indicator (TIOCPKTDATA). select() should be used by the master-side server before each write() request to properly handle INPUT flow control (see select(2)).

When INPUT flow control is enabled, write() and select() are handled as follows: Write-selects on the master side of a pty return true only if INPUT has not been stopped. If INPUT becomes stopped while data is being written into the master side of a pty, the write returns with the number of bytes written before INPUT was stopped. Writes done after INPUT is stopped return immediately with zero bytes written.

When packet mode (TIOCPKT) is disabled and OUTPUT is stopped (see IXON, input modes in termio(7)), each subsequent read() from the master side of a pty returns with no data read. When OUTPUT is restarted, each subsequent read() from the master side returns data written on the slave side. If packet mode (TIOCPKT) is enabled, the first read() after OUTPUT has been stopped returns a TIOCPKTSTOP packet. All subsequent reads from the master side while OUTPUT is stopped returns a TIOCPKTDATA packet with no data. When OUTPUT is restarted, the next read() from the master side returns a TIOCPKTSTART packet. All subsequent reads from the master side return data written on the slave side preceded by a TIOCPKTDATA packet. select() should be used by the master-side server before each read() to properly handle OUTPUT flow control. Otherwise, reads from the master side of a pty will not be prevented when OUTPUT is stopped.

Trapping ioctl(), open(), close() Requests

When trapping is enabled, the master side is notified when the application on its slave side makes an ioctl(), open(), or close() request. For trapped ioctl() and open() requests, the slave side is blocked (that is, the request does not complete) until the server on its master side acknowledges the trapped request. For trapped close() requests, the slave slave does not block for an acknowledgement.

select() should be used by the master side server to receive notification of trapped ioctl(), open(), and close() requests. When one of these requests is trapped, the select() returns with an "exceptional condition" indicated for the slave side's file descriptor. Other mechanisms for receiving notification of trapped requests are defined below, but these mechanisms should be used only if select() is not available.

When trapping is disabled (default condition), unrecognized slave ioctl() requests return an error, with the external variable errno set to EINVAL. The only ioctl() requests recognized by the slave side are those defined by termio(7) and only when TIOCTTY is enabled. When TIOCTTY is disabled, no ioctl() requests are recognized by the slave side. If trapping is enabled and the master side closes, trapping is disabled. If the master closes during the middle of a handshake with the slave, the 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. Trapping ioctl() requests defined by termio(7) are enabled or disabled by TIOCTRAP only when TIOCTTY is also disabled. When TIOCTTY is enabled, trapping ioctl() requests defined by termio(7) are enabled or disabled by TIOCMONITOR. Briefly, both TIOCTRAP and TIOCMONITOR trapping allow the server on the master side to examine the request's parameters, the pid making the request, etc. In addition, TIOCTRAP trapping allows the server to modify the parameters and return values of an ioctl() request.

The following ioctl() calls apply only to the master side of a pty and pertain to trapping ioctl(), open(), and close() requests. They are defined in <sys/ptyio.h>:

TIOCTRAP

Enable or disable trapping of ioctl(), open(), and close() requests made by the application on the slave side of a pty. Trapping is enabled if the int addressed by arg is nonzero and disabled if the int addressed by arg is zero. By default, TIOCTRAP trapping is disabled.

TIOCTRAPSTATUS

Check for a pending ioctl(), open(), or close() trap. The argument points to an int that is set to one if a trap is pending and to zero if nothing is pending. Use TIOCTRAPSTATUS when the preferred method of a select() "exceptional condition" is not available.

TIOCREQCHECK

Return the trapped ioctl(), open(), or close() information to the master side. Use TIOCREQCHECK in response to either a select() "exceptional condition" or a TIOCTRAPSTATUS indicating that a trap is pending. A TIOCREQCHECK reads the pending ioctl(), open(), or close() information into the memory pointed to by the arg of TIOCREQCHECK. The information takes the form of the following request_info structure, defined in <sys/ptyio.h>:

struct request_info { int request; int argget; int argset; pid_t pgrp; pid_t pid; int errno_error; int return_value; };

All elements of request_info refer to the slave side of the pty and include the following:

request

The ioctl() command received.

argget

The ioctl() request applied to master side to receive the trapped ioctl() structure, if one exists (a zero value means there is none). (When nonzero, argget is a TIOCARGGET request with the size field precomputed.)

argset

The ioctl() request applied to master side to send back the resulting ioctl() structure, if one exists (a zero value means there is none). (When nonzero, argset is a TIOCARGSET request with the size field precomputed.)

pgrp

The process group number of the process doing the operation.

pid

The process ID of the process doing the operation.

errno_error

The errno external variable error code (initialized to zero) returned by ioctl() on the slave side. When open error mode is enabled, 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.

When an open() or close() is being passed, request is set to TIOCOPEN or TIOCCLOSE, respectively. For TIOCOPEN and TIOCCLOSE, both argget and argset are zero because there is no ioctl() structure. When TIOCTTY is enabled, the termio(7) definition of open/close is executed first before being passed to the master side. Note that while all opens are trapped, only the last close on a particular inode for a pty slave side is trapped by the pty.

A TIOCREQCHECK returns the external variable errno error EINVAL if no ioctl(), open(), or close() trap is pending. Accordingly, a TIOCREQCHECK that returns EINVAL in response to a select() "exceptional condition" indicates that the trapped ioctl(), open(), or close() request was terminated by a signal after select() returned.

TIOCREQGET

Identical to TIOCREQCHECK except when no ioctl(), open(), or close() trap is pending. A TIOCREQGET blocks until a slave side ioctl(), open(), or close() is trapped; whereas a TIOCREQCHECK returns EINVAL. Use TIOCREQGET when neither the preferred method of a select() "exceptional condition" nor the master side ioctl() TIOCTRAPSTATUS is available.

TIOCREQSET

Complete the handshake started by a previous TIOCREQCHECK or TIOCREQGET. The argument should point to the request_info structure, as defined by the TIOCREQCHECK.

Before doing this ioctl() request to complete the handshake, the server should set errno_error to an external variable errno error value to be passed back to the slave side. If there is no error, errno_error can be left alone because the pty initializes it to zero. Also, when there is no error, return_value should be set if other than a zero result is desired. The server can set return_value and errno_error if the trapped request is an ioctl() and may set errno_error for a trapped open() if open error mode is enabled. Setting either return_value or errno_error for a trapped close() affects neither the return value of the request nor the external variable errno value of the slave side. Setting either return_value or errno_error for a trapped open() affects neither the return value of the request nor the external variable errno value of the slave side unless open error mode is enabled. Open error mode allows the server to return an error to a trapped slave open() by setting errno_error. Unlike ioctl() requests, setting return_value never affects slave pty open() requests. Further, setting either return_value or errno_error does not cause TIOCREQSET to return an error to the server.

If the TIOCREQSET request is made and the request value in the passed request_info structure does not equal the trapped value, the external variable errno is set and returned as EINVAL. EINVAL is also returned if there are no trapped ioctl(), open(), or close() requests. If the trapped request has been interrupted by a signal between the time that the server has done the TIOCREQGET and the TIOCREQSET, the TIOCREQSET request returns EINVAL.

TIOCGFLAGS

Get the file status flags associated with a trapped request. Upon successful return, the ioctl() returns in an integer referenced by arg the file status flags for the trapped request. The flag definitions in <sys/file.h> can be used to interpret the flags. If no trap is currently pending, the TIOCGFLAGS ioctl() returns an error with the external variable errno set to EINVAL.

TIOCMONITOR

Enable or disable read-only trapping of termio ioctl() requests. TIOCMONITOR 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.

When TIOCTTY is disabled, termio ioctl() requests are not trapped by TIOCMONITOR. However, ioctl() requests are trapped by TIOCTRAP if TIOCTTY is disabled and TIOCTRAP is enabled. TIOCTRAP trapping allows the master side server to modify the parameters and return values of an ioctl() request, whereas TIOCTMONITOR trapping does not.

TIOCMONITOR trapping allows the server on the master side to know when characteristics of the line discipline in the pty are changed by an application on its slave side. The mechanism for handshaking termio requests trapped by TIOCMONITOR is the same as the mechanism described above for requests trapped by TIOCTRAP. (It is recommended that termio ioctl() requests be used on the master side to interrogate the configured state of the line discipline in the pty. This compensates for the window of time before TIOCMONITOR is enabled, when termio ioctl() requests are not trapped.)

When using select() on the master side of a pty, the "exceptional condition" refers to an open(), close(), or ioctl() request pending on the slave side, while "ready for reading or writing" indicates that the device can be read from or written to successfully.

Of the ioctl() requests subject to being trapped, only one-per-pty can be handled at a time. This means that when an application does a non-termio ioctl() request to the slave side, all other ioctl() requests to the same pty slave side are blocked until the first one is handshaked back by the master side. (ioctl() requests that are not trapped, such as termio when TIOCTTY is enabled and TIOCMONITOR is disabled, are not blocked.) This permits the implementation of indivisible operations by an ioctl() call on the slave side that is passed to the server process.

In summary, the following method of handling trapped ioctl(), open(), and close() requests is preferred:

1.

Call select(). This system call blocks the master side until a slave side ioctl(), open(), or close() request is trapped.

2.

Make TIOCREQCHECK ioctl() request. This step returns information about a trapped ioctl(), open(), or close() request. If TIOCREQCHECK returns the external variable errno error EINVAL, loop back to the select() call.

3.

Make argget ioctl() request. This optional step is used if argget is nonzero and the server wants to do more than just reject the trapped slave ioctl() request.

4.

Make argset ioctl() request. This optional step is done if argset is nonzero and the server wants to pass back a modified ioctl() structure. It is done after the trapped ioctl() request is processed via the server on the master side.

5.

Set errno_error and return_value. If the trapped request is an ioctl(), set errno_error appropriately. If the appropriate value for errno_error is zero, return_value must be set. If open error mode is enabled, set errno_error to a nonzero value to return an error to a trapped open() request.

6.

Make TIOCREQSET ioctl() request. This step completes the trapped ioctl(), open(), or close() request.

While a process is waiting in the slave side of the pty for the server to complete a handshake, it is susceptible to receiving signals. The following master side ioctl() request allows the server process to control how the pty responds when a signal attempts to interrupt a trapped open() or ioctl() request:

TIOCSIGMODE

Set the signal handling state of the pty to the mode specified as the argument. The mode can have three values, which are TIOCSIGBLOCK, TIOCSIGABORT, and TIOCSIGNORMAL.

TIOCSIGBLOCK

Cause some signals to be postponed that are destined for the slave-side process 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. Any signals that the user has blocked by means of sigblock() continues to be blocked.

TIOCSIGABORT

Prevent a trapped open() or ioctl() request from being restarted. The server process sets this mode when it wants the interrupted requests to return to the calling program with an EINTR error.

TIOCSIGNORMAL

This is the default mode of the pty. If a signal interrupts a trapped open() or ioctl() request, the user's signal handler routine can specify whether the request is to be restarted. If the request is restarted, it executes again from the beginning and the server has to make another TIOCREQGET request to start the handshake over again. If the user's signal handler routine specifies that the interrupted request should not be restarted, the request returns to the calling program with EINTR upon completion of the signal handler. Note that the restarted request is not necessarily the very next one to be trapped.

The following ioctl() requests, defined in <sys/ptyio.h>, provide a mechanism to get and set pty modes. Five of the modes can also be manipulated using other ioctl() requests discussed previously. See the bit definitions for the ioctl() equivalents. The effect of enabling or disabling them by either means is identical. Commonly, an application would use the TIOCGMODES ioctl() to get the pty modes currently in effect, set or clear the bits for the modes being changed, and issue a TIOCGMODES ioctl() to effect the desired change.

TIOCGMODES

Get the pty modes currently in effect. The ioctl() returns in a long referenced by arg bits indicating the states of various pty modes. If a bit is set, the associated mode is enabled. If a bit is clear, the associated mode is disabled. Unused bits are clear. The meaning of the bits is described under the description of the TIOCSMODES ioctl().

TIOCSMODES

Set the pty modes according to the value of type long referenced by arg. Unused bits are ignored but should be set to zero. The bit values for pty modes are listed below.

PM_REMOTE

Enable or disable remote mode. See the discussion of the TIOCREMOTE ioctl().

PM_TTY

Enable or disable tty mode. See the discussion of the TIOCTTY ioctl().

PM_PKT

Enable or disable packet mode. See the discussion of the TIOCPKT ioctl().

PM_TRAP

Enable or disable trap mode. See the discussion of the TIOCTRAP ioctl().

PM_MONITOR

Enable or disable monitor mode. See the discussion of the TIOCMONITOR ioctl().

PM_OPEN_ERROR

Enable or disable open error mode. Open error mode allows a server process to return an error to a trapped slave pty open() through the TIOCREQSET ioctl(). When open error mode is enabled, the server may return a trapped open() with an error by setting the errno_error field in the request_info structure passed to the TIOCREQSET ioctl(). When open error mode is disabled (the default state), setting errno_error to handshake a slave open() has no effect. Note that unlike the ioctl() trap handshaking, setting return_value has no effect for a slave open() regardless of the state of open error mode. See the discussion of the TIOCREQSET ioctl() for further details on handshaking a trapped request.

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.

FILES

/dev/ptym/pty[a-ce-su-z][0-9][0-9]

master pseudo terminals

/dev/ptym/pty[a-ce-su-z][0-9][0-9][0-9]

master pseudo terminals

/dev/ptym/pty[a-ce-su-z][0-9a-f]

master pseudo terminals

/dev/pty[pqr][0-9a-f]

master pseudo terminals

/dev/pty/tty[a-ce-su-z][0-9][0-9]

slave pseudo terminals

/dev/pty/tty[a-ce-su-z][0-9][0-9][0-9]

slave pseudo terminals

/dev/pty/tty[a-ce-su-z][0-9a-f]

slave pseudo terminals

/dev/tty[pqr][0-9a-f]

slave pseudo terminals

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.