pty(7)pty(7)NAMEpty - 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 pre‐
sented 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 dis‐
cussed in the next section.
An attempt to open a nonexistent returns and sets to If is not speci‐
fied, 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 master
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 use‐
ful 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 recognizes
requests defined by termio(7). An request made on the slave side of a
after the master side is closed returns and sets the external variable
to An request not recognized by the returns and sets the external vari‐
able to Note that some of the master-side-only requests affect which
requests are recognized by the master and slave side of the These mas‐
ter-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 signal(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 pro‐
cessing 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 dis‐
abling 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 imple‐
mentation 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 operate.
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 reflecting
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 ter‐
minal 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 char‐
acter (that is, the EOF character as defined in
termio(7)). The data read by the slave side is identi‐
cal to the data written on the master side. Data writ‐
ten on the slave side and read on the master side with
enabled is still subject to the normal termio(7) pro‐
cessing. 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 termi‐
nal. Takes no parameter.
Stop data flowing from the slave side of the
to the master side (equivalent to typing Takes no param‐
eter.
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 mas‐
ter 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 applica‐
tion 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 acknowl‐
edgement.
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 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 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 dis‐
abled. 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 disabled 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 condi‐
tion" 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 pending. A reads the pending or information
into the memory pointed to by the arg of The information
takes the form of the following 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 opera‐
tion.
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 structure. 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 "excep‐
tional 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 preferred method of a "exceptional condi‐
tion" 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. Set‐
ting 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 refer‐
enced by arg the file status flags for the trapped
request. The flag definitions in can be used to inter‐
pret 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 mecha‐
nism 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 suc‐
cessfully.
Of the requests subject to being trapped, only one-per-pty can be han‐
dled 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 fol‐
lowing 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 otherwise cause the process to jump to
an installed signal handler. Signals are not post‐
poned 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 inter‐
rupted 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 refer‐
enced 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 ALSOclose(2), fcntl(2), ioctl(2), open(2), read(2), select(2), sigblock(2),
write(2), ptsname(3C), signal(5), termio(7).
pty(7)
