1 PTY(7D) Devices PTY(7D)
2
3 NAME
4 pty - pseudo-terminal driver
5
6 DESCRIPTION
7 The pty driver provides support for a pair of devices collectively
8 known as a pseudo-terminal. The two devices comprising a pseudo-
9 terminal are known as a controller and a slave. The slave device
10 distinguishes between the B0 baud rate and other baud rates specified
11 in the c_cflag word of the termios structure, and the CLOCAL flag in
12 that word. It does not support any of the other termio(7I) device
13 control functions specified by flags in the c_cflag word of the termios
14 structure and by the IGNBRK, IGNPAR, PARMRK, or INPCK flags in the
15 c_iflag word of the termios structure, as these functions apply only to
16 asynchronous serial ports. All other termio(7I) functions must be
17 performed by STREAMS modules pushed atop the driver; when a slave
18 device is opened, the ldterm(7M) and ttcompat(7M) STREAMS modules are
19 automatically pushed on top of the stream, providing the standard
20 termio(7I) interface.
21
22
23 Instead of having a hardware interface and associated hardware that
24 supports the terminal functions, the functions are implemented by
25 another process manipulating the controller device of the pseudo-
26 terminal.
27
28
29 The controller and the slave devices of the pseudo-terminal are tightly
30 connected. Any data written on the controller device is given to the
31 slave device as input, as though it had been received from a hardware
32 interface. Any data written on the slave terminal can be read from the
33 controller device (rather than being transmitted from a UAR).
34
35
36 By default, 48 pseudo-terminal pairs are configured as follows:
37
38 /dev/pty[p-r][0-9a-f] controller devices
39 /dev/tty[p-r][0-9a-f] slave devices
40
41
42 IOCTLS
43 The standard set of termio ioctls are supported by the slave device.
44 None of the bits in the c_cflag word have any effect on the pseudo-
45 terminal, except that if the baud rate is set to B0, it will appear to
46 the process on the controller device as if the last process on the
47 slave device had closed the line; thus, setting the baud rate to B0 has
48 the effect of ``hanging up'' the pseudo-terminal, just as it has the
49 effect of ``hanging up'' a real terminal.
50
51
52 There is no notion of ``parity'' on a pseudo-terminal, so none of the
53 flags in the c_iflag word that control the processing of parity errors
54 have any effect. Similarly, there is no notion of a ``break'', so none
55 of the flags that control the processing of breaks, and none of the
56 ioctls that generate breaks, have any effect.
57
58
59 Input flow control is automatically performed; a process that attempts
60 to write to the controller device will be blocked if too much
61 unconsumed data is buffered on the slave device. The input flow
62 control provided by the IXOFF flag in the c_iflag word is not
63 supported.
64
65
66 The delays specified in the c_oflag word are not supported.
67
68
69 As there are no modems involved in a pseudo-terminal, the ioctls that
70 return or alter the state of modem control lines are silently ignored.
71
72
73 A few special ioctls are provided on the controller devices of pseudo-
74 terminals to provide the functionality needed by applications programs
75 to emulate real hardware interfaces:
76
77 TIOCSTOP
78 The argument is ignored. Output to the pseudo-terminal is
79 suspended, as if a STOP character had been typed.
80
81
82 TIOCSTART
83 The argument is ignored. Output to the pseudo-terminal is
84 restarted, as if a START character had been typed.
85
86
87 TIOCPKT
88 The argument is a pointer to an int. If the value of the
89 int is non-zero, packet mode is enabled; if the value of
90 the int is zero, packet mode is disabled. When a pseudo-
91 terminal is in packet mode, each subsequent read(2) from
92 the controller device will return data written on the
93 slave device preceded by a zero byte (symbolically
94 defined as TIOCPKT_DATA), or a single byte reflecting
95 control status information. In the latter case, the byte
96 is an inclusive-or of zero or more of the bits:
97
98 TIOCPKT_FLUSHREAD
99 whenever the read queue for the
100 terminal is flushed.
101
102
103 TIOCPKT_FLUSHWRITE
104 whenever the write queue for the
105 terminal is flushed.
106
107
108 TIOCPKT_STOP
109 whenever output to the terminal is
110 stopped using ^S.
111
112
113 TIOCPKT_START
114 whenever output to the terminal is
115 restarted.
116
117
118 TIOCPKT_DOSTOP
119 whenever XON/XOFF flow control is
120 enabled after being disabled; it is
121 considered ``enabled'' when the
122 IXON flag in the c_iflag word is
123 set, the VSTOP member of the c_cc
124 array is ^S and the VSTART member
125 of the c_cc array is ^Q.
126
127
128 TIOCPKT_NOSTOP
129 whenever XON/XOFF flow control is
130 disabled after being enabled.
131
132
133
134 TIOCREMOTE
135 The argument is a pointer to an int. If the value of the
136 int is non-zero, remote mode is enabled; if the value of
137 the int is zero, remote mode is disabled. This mode can
138 be enabled or disabled independently of packet mode. When
139 a pseudo-terminal is in remote mode, input to the slave
140 device of the pseudo-terminal is flow controlled and not
141 input edited (regardless of the mode the slave side of
142 the pseudo-terminal). Each write to the controller device
143 produces a record boundary for the process reading the
144 slave device. In normal usage, a write of data is like
145 the data typed as a line on the terminal; a write of 0
146 bytes is like typing an EOF character. Note: this means
147 that a process writing to a pseudo-terminal controller in
148 remote mode must keep track of line boundaries, and write
149 only one line at a time to the controller. If, for
150 example, it were to buffer up several NEWLINE characters
151 and write them to the controller with one write(), it
152 would appear to a process reading from the slave as if a
153 single line containing several NEWLINE characters had
154 been typed (as if, for example, a user had typed the
155 LNEXT character before typing all but the last of those
156 NEWLINE characters). Remote mode can be used when doing
157 remote line editing in a window manager, or whenever flow
158 controlled input is required.
159
160
161 EXAMPLES
162 #include <fcntl.h>
163 #include <sys/termios.h>
164
165 int fdm fds;
166 fdm = open("/dev/ptyp0, O_RDWR); /* open master */
167 fds = open("/dev/ttyp0, O_RDWR); /* open slave */
168
169
170 FILES
171 /dev/pty[p-z][0-9a-f]
172 pseudo-terminal controller devices
173
174
175 /dev/tty[p-z][0-9a-f]
176 pseudo-terminal slave devices
177
178
179 SEE ALSO
180 rlogin(1), rlogind(1M), ldterm(7M), termio(7I), ttcompat(7M),
181
182 NOTES
183 It is apparently not possible to send an EOT by writing zero bytes in
184 TIOCREMOTE mode.
185
186 August 8, 1994 PTY(7D)
|
1 PTY(7D) Devices PTY(7D)
2
3 NAME
4 pty - legacy pseudo-terminal driver
5
6 SYNOPSIS
7 /dev/pty[p-r]*
8
9 /dev/tty[p-r]*
10
11 DESCRIPTION
12 This driver provides support for legacy static pseudo-terminal devices.
13 Modern software does not use this driver, preferring instead the STREAMS-
14 based ptm(7D) and pts(7D) pseudo-terminal drivers, consumed through the
15 portable posix_openpt(3C) interface.
16
17 The pty driver provides support for a pair of devices collectively known
18 as a pseudo-terminal. The two devices comprising a pseudo-terminal are
19 known as a manager and a subsidiary. The subsidiary device distinguishes
20 between the B0 baud rate and other baud rates specified in the c_cflag
21 field of the termios structure, and the CLOCAL flag in that member. It
22 does not support any of the other termio(7I) device control functions
23 specified by flags in the c_cflag field of the termios structure and by
24 the IGNBRK, IGNPAR, PARMRK, or INPCK flags in the c_iflag field of the
25 termios structure, as these functions apply only to asynchronous serial
26 ports. All other termio(7I) functions must be performed by STREAMS
27 modules pushed atop the driver; when a subsidiary device is opened, the
28 ldterm(7M) and ttcompat(7M) STREAMS modules are automatically pushed on
29 top of the stream, providing the standard termio(7I) interface.
30
31 Instead of having a hardware interface and associated hardware that
32 supports the terminal functions, the functions are implemented by another
33 process manipulating the manager device of the pseudo-terminal.
34
35 The manager and the subsidiary devices of the pseudo-terminal are tightly
36 connected. Any data written on the manager device is given to the
37 subsidiary device as input, as though it had been received from a
38 hardware interface. Any data written on the subsidiary terminal can be
39 read from the manager device (rather than being transmitted from a UAR).
40
41 The driver is statically configured to provide 48 pseudo-terminal pairs.
42 Software that requires dynamic pseudo-terminal devices, or a greater
43 number of devices, must be converted to use ptm(7D).
44
45 IOCTLS
46 The standard set of termio(7I) ioctls are supported by the subsidiary
47 device. None of the bits in the c_cflag field have any effect on the
48 pseudo-terminal, except that if the baud rate is set to B0, it will
49 appear to the process on the manager device as if the last process on the
50 subsidiary device had closed the line; thus, setting the baud rate to B0
51 has the effect of "hanging up" the pseudo-terminal, just as it has the
52 effect of "hanging up" a real terminal.
53
54 There is no notion of "parity" on a pseudo-terminal, so none of the flags
55 in the c_iflag field that control the processing of parity errors have
56 any effect. Similarly, there is no notion of a break, so none of the
57 flags that control the processing of breaks, and none of the ioctls that
58 generate breaks, have any effect.
59
60 Input flow control is automatically performed; a process that attempts to
61 write to the manager device will be blocked if too much unconsumed data
62 is buffered on the subsidiary device. The input flow control provided by
63 the IXOFF flag in the c_iflag field is not supported.
64
65 The delays specified in the c_oflag field are not supported.
66
67 As there are no modems involved in a pseudo-terminal, the ioctls that
68 return or alter the state of modem control lines are silently ignored.
69
70 A few special ioctls are provided on the manager devices of pseudo-
71 terminals to provide the functionality needed by applications programs to
72 emulate real hardware interfaces:
73
74 TIOCSTOP
75 The argument is ignored. Output to the pseudo-terminal is
76 suspended, as if a STOP character had been typed.
77
78 TIOCSTART
79 The argument is ignored. Output to the pseudo-terminal is
80 restarted, as if a START character had been typed.
81
82 TIOCPKT
83 The argument is a pointer to an int. If the value of the int is
84 non-zero, packet mode is enabled; if the value of the int is
85 zero, packet mode is disabled. When a pseudo-terminal is in
86 packet mode, each subsequent read(2) from the manager device will
87 return data written on the subsidiary device preceded by a zero
88 byte (symbolically defined as TIOCPKT_DATA), or a single byte
89 reflecting control status information. In the latter case, the
90 byte is an inclusive-or of zero or more of the bits:
91
92 TIOCPKT_FLUSHREAD
93 Whenever the read queue for the terminal is flushed.
94
95 TIOCPKT_FLUSHWRITE
96 Whenever the write queue for the terminal is flushed.
97
98 TIOCPKT_STOP
99 Whenever output to the terminal is stopped using ^S.
100
101 TIOCPKT_START
102 Whenever output to the terminal is restarted.
103
104 TIOCPKT_DOSTOP
105 Whenever XON/XOFF flow control is enabled after being
106 disabled; it is considered "enabled" when the IXON flag
107 in the c_iflag field is set, the VSTOP member of the c_cc
108 array is ^S and the VSTART member of the c_cc array is
109 ^Q.
110
111 TIOCPKT_NOSTOP
112 Whenever XON/XOFF flow control is disabled after being
113 enabled.
114
115 TIOCREMOTE
116 The argument is a pointer to an int. If the value of the int is
117 non-zero, remote mode is enabled; if the value of the int is
118 zero, remote mode is disabled. This mode can be enabled or
119 disabled independently of packet mode. When a pseudo-terminal is
120 in remote mode, input to the subsidiary device of the pseudo-
121 terminal is flow controlled and not input edited (regardless of
122 the mode the subsidiary side of the pseudo-terminal).
123
124 Each write to the manager device produces a record boundary for
125 the process reading the subsidiary device. In normal usage, a
126 write of data is like the data typed as a line on the terminal; a
127 write of 0 bytes is like typing an EOF character. Note: this
128 means that a process writing to a pseudo-terminal manager in
129 remote mode must keep track of line boundaries, and write only
130 one line at a time to the manager.
131
132 If, for example, it were to buffer up several newline characters
133 and write them to the manager with one write(2), it would appear
134 to a process reading from the subsidiary as if a single line
135 containing several newline characters had been typed (as if, for
136 example, a user had typed the literal next (LNEXT) character
137 before typing all but the last of those newline characters).
138 Remote mode can be used when doing remote line editing in a
139 window manager, or whenever flow controlled input is required.
140
141 FILES
142 /dev/pty[p-r][0-9a-f] Pseudo-terminal manager devices.
143
144 /dev/tty[p-r][0-9a-f] Pseudo-terminal subsidiary devices.
145
146 SEE ALSO
147 rlogin(1), rlogind(1M), posix_openpty(3C), ptm(7D), termio(7I),
148 ldterm(7M), ttcompat(7M)
149
150 NOTES
151 This is a legacy device and should not be used by new software.
152
153 It is apparently not possible to send an EOT by writing zero bytes in
154 TIOCREMOTE mode.
155
156 illumos February 5, 2022 illumos
|