pty(7) Miscellaneous Information Manual pty(7)
NAME
pty - pseudo-terminal driver
DESCRIPTION
The 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 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 is permitted. An attempt to open an already open master side returns and sets the external variable to An
attempt to open the master side of a that has a slave with an open file descriptor returns and sets to The potential problem of 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 returns and sets to If is not specified, opens on the slave side hang until the master side is opened. If
is specified, opens on the slave side return error if the master side is closed. Any or request made on the slave side of a after the mas-
ter side is closed returns and sets the external variable to A request made on the slave side of a after the master side is closed returns
0 bytes. Closing the master side of a sends a hangup signal to the tty process group number of the corresponding slave side and flushes
pending input and output.
Clone Open
In typical usage, there is no preference among pairs. Thus, it is useful to be able to issue a single that internally opens any available
An open on returns an open file descriptor of a free master device. If there are no free devices, the open returns and sets to The name of
the slave device corresponding to the opened master device can be found through a request.
Processing ioctl() Requests
By default, any request defined by termio(7) is recognized by both the master and slave sides of a These requests are processed by the
driver as specified by termio(7). In addition, the requests defined below are recognized by the master side of a The slave side only rec-
ognizes requests defined by termio(7). An request made on the slave side of a after the master side is closed returns and sets the exter-
nal variable to An request not recognized by the returns and sets the external variable to Note that some of the master-side-only requests
affect which requests are recognized by the master and slave side of the These master-side-only requests also affect the way recognized
requests, requests, and requests are processed by the driver.
The following requests, defined in apply only to the master side of
Cause a signal to be sent from the slave side of the
to the current tty process group of the slave side. The value of the parameter is taken to be the signal number sent. An
error is returned and no signal is sent if the specified signal number does not refer to a legitimate signal (see sig-
nal(5)). Note that this request allows the server process to send signals to processes not owned by the same user ID.
Enable or disable all
processing by a processing is enabled if the addressed by arg is nonzero and disabled if the addressed by arg is zero. By
default, processing is enabled. processing refers to processing of input and output described by termio(7) (such as tab
expansion), as well as the processing of the requests described by termio(7). When disabled, all input and output data is
passed through the without modification. Issuing a request flushes all data buffered in the pseudo terminal and releases
any processes blocked waiting for data. Enabling and disabling affects the operation of the following requests: and
When is enabled, all requests execute as specified in termio(7), regardless of the side from which the request is made.
When is disabled, master side requests set and return the the external variable to Slave side requests are processed like
any other request when is disabled. In particular, slave side requests set and return the external variable to when both
and are disabled. (See the discussion of and trapping below). requests not defined by termio(7) are not affected by the
state of
Data written through a pseudo terminal with disabled is handled in a manner similar to data flowing through a pipe. A write
request blocks in the until all data has been written into the A read request blocks if there is no data available unless
the 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 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 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 requests, defined in apply only to the master side of a In particular, these requests enable/disable specific modes of driver
operation. These requests work in series with that is, the mode must be enabled by its request and must be enabled for the mode to oper-
ate. The mode can be enabled or disabled regardless of the state of
Enable or disable packet mode.
Packet mode is enabled if the addressed by arg is nonzero and disabled if the addressed by arg is zero. By default, packet
mode is disabled. When applied to the master side of a pseudo terminal, each subsequent from the master side returns data
written on the slave part of the pseudo terminal preceded by a zero byte (symbolically defined as or a single byte reflect-
ing control status information. The value of such a status byte is composed of zero or more bit flags:
The read queue for the slave side has been flushed.
The write queue for the slave side has been flushed.
Data flowing from the slave side of the
to the master side has been stopped by means of or
Data flowing from the slave side of the
to the master side has been restarted.
Stop and start characters have been set to
or
Stop and start characters are set to something other than
or
Enable or disable remote mode.
Remote mode is enabled if the value of arg is nonzero and disabled if the 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 mas-
ter side with enabled is still subject to the normal termio(7) processing. can be used when doing remote line editing in a
window manager, or whenever flow-controlled input is required. Issuing a request flushes all data buffered in the pseudo
terminal.
The following requests, defined in apply only to the master side of In particular, these requests are only recognized when is enabled.
When is disabled, these requests set and return the external variable to
Cause a break operation to be done on the slave side of the
as if a user had pressed the break key on a real terminal. Takes no parameter.
Stop data flowing from the slave side of the
to the master side (equivalent to typing Takes no parameter.
Restart output (stopped by
or by typing 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
to the slave side. OUTPUT refers to data flowing from the slave side of a to the master side.
When packet mode is disabled and INPUT is stopped (see IXOFF, input modes, in termio(7)), the next from the master side of a returns a STOP
character. When INPUT is restarted, the next from the master side returns a START character. If packet mode is enabled, the STOP or START
character is preceded by a data packet indicator should be used by the master-side server before each request to properly handle INPUT flow
control (see select(2)).
When INPUT flow control is enabled, and are handled as follows: Write-selects on the master side of a return true only if INPUT has not
been stopped. If INPUT becomes stopped while data is being written into the master side of a 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 is disabled and OUTPUT is stopped (see IXON, input modes in termio(7)), each subsequent from the master side of a returns
with no data read. When OUTPUT is restarted, each subsequent from the master side returns data written on the slave side. If packet mode
is enabled, the first after OUTPUT has been stopped returns a packet. All subsequent reads from the master side while OUTPUT is stopped
returns a packet with no data. When OUTPUT is restarted, the next from the master side returns a packet. All subsequent reads from the
master side return data written on the slave side preceded by a packet. should be used by the master-side server before each to properly
handle OUTPUT flow control. Otherwise, reads from the master side of a 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 or request. For trapped and
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 requests, the slave slave does not block for an acknowledgement.
should be used by the master side server to receive notification of trapped and requests. When one of these requests is trapped, the
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 is not available.
When trapping is disabled (default condition), unrecognized slave requests return an error, with the external variable set to The only
requests recognized by the slave side are those defined by termio(7) and only when is enabled. When is disabled, no requests are recog-
nized 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 requests that enable or disable them -- and These two forms are distinguished by
the types of requests they affect and by the capabilities they provide. Trapping and requests is enabled or disabled by Trapping requests
not defined by termio(7) are enabled or disabled by Trapping requests defined by termio(7) are enabled or disabled by only when is also
disabled. When is enabled, trapping requests defined by termio(7) are enabled or disabled by Briefly, both and trapping allow the server
on the master side to examine the request's parameters, the pid making the request, etc. In addition, trapping allows the server to modify
the parameters and return values of an request.
The following calls apply only to the master side of a and pertain to trapping and requests. They are defined in
Enable or disable trapping of
and requests made by the application on the slave side of a Trapping is enabled if the addressed by arg is nonzero and dis-
abled if the addressed by arg is zero. By default, trapping is disabled.
Check for a pending
or trap. The argument points to an that is set to one if a trap is pending and to zero if nothing is pending. Use when the
preferred method of a "exceptional condition" is not available.
Return the trapped
or information to the master side. Use in response to either a "exceptional condition" or a indicating that a trap is pend-
ing. A reads the pending or information into the memory pointed to by the arg of The information takes the form of the fol-
lowing structure, defined in
All elements of refer to the slave side of the and include the following:
The command received.
The request applied to master side to receive the trapped structure, if one exists (a zero value means there is
none). (When nonzero, is a request with the size field precomputed.)
The request applied to master side to send back the resulting structure, if one exists (a zero value means there
is none). (When nonzero, is a request with the size field precomputed.)
The process group number of the process doing the operation.
The process ID of the process doing the operation.
The external variable error code (initialized to zero) returned by on the slave side. When open error mode is
enabled, can be used to return an error for trapped slave requests. See the discussion of the for further
information on open error mode.
The success value (initialized to zero) returned by
on the slave side when is not set.
When the argument received on the slave side is not a pointer, its value is stored as four bytes retrievable
with an request to the master side equal to
When an or is being passed, is set to or respectively. For and both and are zero because there is no struc-
ture. When 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 slave
side is trapped by the
A returns the external variable error if no or trap is pending. Accordingly, a that returns in response to a
"exceptional condition" indicates that the trapped or request was terminated by a signal after returned.
Identical to except when no or trap is pending. A blocks until a slave side or is trapped; whereas a returns Use when neither the pre-
ferred method of a "exceptional condition" nor the master side is available.
Complete the handshake started by a previous
or The argument should point to the structure, as defined by the
Before doing this request to complete the handshake, the server should set to an external variable error value to be passed
back to the slave side. If there is no error, can be left alone because the initializes it to zero. Also, when there is no
error, should be set if other than a zero result is desired. The server can set and if the trapped request is an and may
set for a trapped if open error mode is enabled. Setting either or for a trapped affects neither the return value of the
request nor the external variable value of the slave side. Setting either or for a trapped affects neither the return value
of the request nor the external variable 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 by setting Unlike requests, setting never affects slave requests. Further,
setting either or does not cause to return an error to the server.
If the request is made and the request value in the passed structure does not equal the trapped value, the external variable
is set and returned as is also returned if there are no trapped or requests. If the trapped request has been interrupted by
a signal between the time that the server has done the and the the request returns
Get the file status flags associated with a trapped request.
Upon successful return, the returns in an integer referenced by arg the file status flags for the trapped request. The flag
definitions in can be used to interpret the flags. If no trap is currently pending, the returns an error with the external
variable set to
Enable or disable read-only trapping of
requests. trapping is enabled if the addressed by arg is nonzero and disabled if the addressed by arg is zero. By default,
trapping is disabled. works in series with that is, the trapping must be enabled and must be enabled for requests to be
trapped by trapping can be enabled or disabled regardless of the state of
When is disabled, requests are not trapped by However, requests are trapped by if is disabled and is enabled. trapping
allows the master side server to modify the parameters and return values of an request, whereas trapping does not.
trapping allows the server on the master side to know when characteristics of the line discipline in the are changed by an
application on its slave side. The mechanism for handshaking requests trapped by is the same as the mechanism described
above for requests trapped by (It is recommended that requests be used on the master side to interrogate the configured
state of the line discipline in the This compensates for the window of time before is enabled, when requests are not
trapped.)
When using on the master side of a the "exceptional condition" refers to an or 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 requests subject to being trapped, only one-per-pty can be handled at a time. This means that when an application does a request to
the slave side, all other requests to the same slave side are blocked until the first one is handshaked back by the master side. requests
that are not trapped, such as when is enabled and is disabled, are not blocked.) This permits the implementation of indivisible operations
by an call on the slave side that is passed to the server process.
In summary, the following method of handling trapped and requests is preferred:
1. Call This system call blocks the master side until a slave side or request is trapped.
2. Make request. This step returns information about a trapped or request. If returns the external variable error loop back to
the call.
3. Make request. This optional step is used if is nonzero and the server wants to do more than just reject the trapped slave
request.
4. Make request. This optional step is done if is nonzero and the server wants to pass back a modified structure. It is done
after the trapped request is processed via the server on the master side.
5. Set and If the trapped request is an set appropriately. If the appropriate value for is zero, must be set. If open error mode
is enabled, set to a nonzero value to return an error to a trapped request.
6. Make request. This step completes the trapped or request.
While a process is waiting in the slave side of the for the server to complete a handshake, it is susceptible to receiving signals. The
following master side request allows the server process to control how the responds when a signal attempts to interrupt a trapped or
request:
Set the signal handling state of the
to the mode specified as the argument. The mode can have three values, which are and
Cause some signals to be postponed
that are destined for the slave-side process whose or request is trapped. Signals are postponed if they would other-
wise 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
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 continues to be blocked.
Prevent a trapped
or request from being restarted. The server process sets this mode when it wants the interrupted requests to return to
the calling program with an error.
This is the default mode of the
If a signal interrupts a trapped or 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
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 upon completion of the signal handler. Note
that the restarted request is not necessarily the very next one to be trapped.
The following requests, defined in provide a mechanism to get and set modes. Five of the modes can also be manipulated using other
requests discussed previously. See the bit definitions for the equivalents. The effect of enabling or disabling them by either means is
identical. Commonly, an application would use the to get the modes currently in effect, set or clear the bits for the modes being changed,
and issue a to effect the desired change.
Get the modes currently in effect. The returns in a long referenced by arg bits indicating the states of various 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
Set the 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 modes are listed below.
Enable or disable remote mode.
See the discussion of the
Enable or disable tty mode.
See the discussion of the
Enable or disable packet mode.
See the discussion of the
Enable or disable trap mode.
See the discussion of the
Enable or disable monitor mode.
See the discussion of the
Enable or disable open error mode.
Open error mode allows a server process to return an error to a trapped slave through the When open error mode is
enabled, the server may return a trapped with an error by setting the field in the structure passed to the TIOCREQSET
When open error mode is disabled (the default state), setting to handshake a slave has no effect. Note that unlike the
trap handshaking, setting has no effect for a slave regardless of the state of open error mode. See the discussion of
the 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 a single 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
was developed by the University of California, Berkeley.
FILES
master pseudo terminals
master pseudo terminals
master pseudo terminals
master pseudo terminals
slave pseudo terminals
slave pseudo terminals
slave pseudo terminals
slave pseudo terminals
SEE ALSO
close(2), fcntl(2), ioctl(2), open(2), read(2), select(2), sigblock(2), write(2), ptsname(3C), signal(5), termio(7).
pty(7)
