PTY(4,F) AIX Technical Reference PTY(4,F)
-------------------------------------------------------------------------------
pty
PURPOSE
Implements a pseudo-terminal device.
SYNOPSIS
#include <sys/devinfo.h>
#include <sys/pty.h>
#include <sys/tty.h>
DESCRIPTION
A pty device is a pair of bi-directional character device drivers that
implement a pseudo-terminal. It is found in all AIX systems. A
pseudo-terminal can act as a keyboard and a display to existing software that
uses the standard terminal device interface described in "termio." This is
useful for a variety of applications such as a remote login facility or a
windowing system.
Each pseudo-terminal (or pty) consists of two device drivers called a
controller and a server (master and slave). The server or server side of a pty
has a standard terminal interface that can support a login shell or other
software that normally communicates with terminals. The controller or
controller side of a pty interfaces with software that generates and receives
data as if it were a user at a terminal. Data written to the controller is
passed directly to the server, which is then read and processed as if entered
from a keyboard. Data written to the server (as if to be displayed on a
terminal screen) is passed directly to the controller.
The corresponding special files are named /dev/ptyxy for the controller and
/dev/ttyxy for the server, where x is taken from the set p-z,A-Z and y is taken
from the set 0-9,a-f. A 1-to-1 correspondence exists between each
controller-server pair with names that end in the same two characters. For
example, /dev/ptyp0 and /dev/ttyp0 together form a pty.
The ptyunits keyword can be set in the sysparms stanza in /etc/system to change
the number of ptys in the system from the default (defined by the ptyunits
stanza in /etc/master).
Use the devices command to add a pty to the system. For applications that
require a login shell on the server side of the pty, configure the pty so the
init program creates a login shell. For IBM remote applications such as
Telnet, do not configure the pty to start a login shell. To determine whether
a particular application requires a login shell on the server side, see the
appropriate application documentation.
Processed November 7, 1990 PTY(4,F) 1
PTY(4,F) AIX Technical Reference PTY(4,F)
When using a pty for applications other than remote login, a program must take
into account the fact that a logger process may have already issued an open to
the server side of the pty. When a logger opens the server side, the open
system call suspends the process to wait for another process to open the
controller side. Use the following strategy to detect this situation:
1. Open /dev/ptyxy.
2. Issue an ioctl system call to perform the PTYSTATUS operation.
3. If the status indicates that the server side has already been opened, then
close the pty controller and try a /dev/ptyxy device with a different value
for xy.
4. If the status indicates that the server side has not been opened, then
open the corresponding /dev/ttyxy device.
Note: The server side of a pty can be opened multiple times, but the
controller can be opened only once. Attempting to open the controller
side more than once causes an error.
SELECT SUPPORT
The pty device driver supports the select system call in the following manner:
o Read selects are satisfied when input data is available.
o Write selects are satisfied when data can be accepted.
o Exception selects are never satisfied, or hang indefinitely if no timeout
value is specified.
See "select" for more information about this system call.
IOCTL OPERATIONS
The interface to the server side of the pty device is identical to the standard
interface for terminals, which is described in "termio."
The controller side of the pty device driver supports the following ioctl
operations. (See "ioctlx, ioctl, gtty, stty" for detailed information about
the ioctl system call.)
IOCTYPE Returns the device type DD_PSEU to indicate that this is a
pseudo-terminal device. This operation ignores the arg parameter.
IOCINFO Copies the devinfo structure for the device into the buffer
pointed to by the arg parameter passed to ioctl. See "devinfo"
for details about this structure.
Processed November 7, 1990 PTY(4,F) 2
PTY(4,F) AIX Technical Reference PTY(4,F)
PTYSTATUS Returns the state of the pty, which is composed of two halfwords.
The upper half contains the number of opens currently outstanding
against the controller, and the lower half contains the number of
opens currently outstanding against the server. This operation
ignores the arg parameter.
PTYIOR Reports the number of characters available to be read. The arg
parameter is a pointer to an integer, into which this value is
stored.
PTYIOW Reports the number of eight bit bytes on the raw and canonical
queues. The arg parameter is a pointer to an integer, into which
this value is stored.
PTYGETM Gets the current mode of the pty. The arg parameter is a pointer
to an integer, into which the mode is stored. See the description
PTYSETM for an explanation of the possible mode values.
PTYSETM Sets the current mode of the pty. The arg parameter is a pointer
to an integer that contains the mode to be set. The mode is zero
or more of the following values logically ORed together:
RAWQINT Sends the SIGIO signal to the process when enough buffer
space is available for writing to the pty.
OUTQINT Sends the SIGIO signal to the process when data is
available to be read.
REMOTE Controls the flow of input to the pty, but does not edit
the input. In other words, START and STOP (Ctrl-S and
Ctrl-Q) controls are processed, but no editing is done on
the data stream (such as ERASE, KILL, or ICRNL).
PTYADDM Adds to the current pty mode by logically ORing the specified
value with the existing mode. The arg parameter is a pointer to
an integer that contains the mode bits to be set. See the
description PTYSETM for an explanation of the possible mode
values.
PTYDELM Deletes from the current pty mode. The arg parameter is a pointer
to an integer. The bits that are set in this integer specify the
mode bits to be turned off. See the description PTYSETM for an
explanation of the possible mode values.
TIOCREMOTE A mode for the controller half of a pseudo-terminal, independent
of TIOCPKT. 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 control terminal produces a record
boundary for the process reading the terminal. In normal usage, a
write of data is like the data typed as a line on the terminal. A
write of 0 bytes is like typing an end-of-file character.
TIOCREMOTE can be used when doing remote line editing in a window
manager, or whenever flow-controlled input is required.
Processed November 7, 1990 PTY(4,F) 3
PTY(4,F) AIX Technical Reference PTY(4,F)
TIOCPKT Enables or disables packet mode. The arg parameter is a pointer
to an integer that contains the packet mode to be enabled or
disabled. The mode is zero or more of the following values
logically ORed together:
TIOCPKT_STOP
Indicates output to the terminal is stopped with STOP
(Ctrl-S) control.
TIOCPKT_START
Indicates output to the terminal has restarted.
TIOCPKT_DOSTOP
Indicates packet mode is stopped when START and STOP
(Ctrl-S and Ctrl-Q) controls are processed.
TIOCPKT_NOSTOP
Indicates packet mode is stopped if the START and STOP
controls are not Ctrl-S and Ctrl-Q.
TIOCUCNTL Enable/disable a mode that allows a small number of simple user
ioctl commands to be passed through the pseudo-terminal, using a
protocol similar to that of TIOCPKT. The TIOCUCNTL and TIOCPKT
modes are mutually exclusive. This mode is enabled from the
controller side of a pseudo-terminal by specifying (by reference)
a nonzero parameter and disabled by specifying (by reference) a
zero parameter. Each subsequent read from the controller side
returns data written on the server part of the pseudo-terminal
preceded by a zero byte, or a single byte reflecting a user
control operation on the server side. A user control command
consists of a special ioctl operation with no data. The command
is given as UIOCCMD(n), where n is a number in the range of 1-255.
The operation value n will be received as a single byte on the
next read from the controller side. The ioctl UIOCCMD(0) is a
no-op that may be used to probe for the existence of this
facility. As with TIOCPKT mode, command operations may be
detected with a select for exceptional conditions.
ERROR CONDITIONS
System calls to a pty device fail and set errno to indicate the error if one or
more of the following are true:
EINVAL An invalid parameter was encountered, such as a negative number of
bytes to be written.
ENXIO The pty cannot be opened because the pty number is out of range.
EIO A read, write, or ioctl operation was attempted that requires both
sides of the pty to be open, making a complete connection.
EACCES An attempt was made to open the controller side of a pty more than
once.
Processed November 7, 1990 PTY(4,F) 4
PTY(4,F) AIX Technical Reference PTY(4,F)
FILES
Controller Devices
/dev/ptyp0, /dev/ptyp1,..., /dev/ptypf, /dev/ptyq1,...,
/dev/ptyzf, /dev/ptyA0,..., /dev/ptyZf
Server Devices
/dev/ttyp0, /dev/ttyp1,..., /dev/ttypf, /dev/ttyq1,...,
/dev/ttyzf, /dev/ttyA0,..., /dev/ttyZf
RELATED INFORMATION
In this book: "ioctlx, ioctl, gtty, stty," "open, openx, creat," "master,"
"ports," "system," and "fcntl.h."
The tn and telnetd commands in AIX TCP/IP User's Guide.
The devices and init commands in AIX Operating System Commands Reference.
Processed November 7, 1990 PTY(4,F) 5