1 '\" te 2 .\" Copyright (c) 1994, Sun Microsystems, Inc. 3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. 4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. 5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] 6 .\" Copyright 2022 Oxide Computer Company 7 .Dd February 5, 2022 8 .Dt PTY 7D 9 .Os 10 .Sh NAME 11 .Nm pty 12 .Nd legacy pseudo-terminal driver 13 .Sh SYNOPSIS 14 .Pa /dev/pty[p-r]* 15 .Pp 16 .Pa /dev/tty[p-r]* 17 .Sh DESCRIPTION 18 This driver provides support for legacy static pseudo-terminal devices. 19 Modern software does not use this driver, preferring instead the STREAMS-based 20 .Xr ptm 7D 21 and 22 .Xr pts 7D 23 pseudo-terminal drivers, consumed through the portable 24 .Xr posix_openpt 3C 25 interface. 26 .Pp 27 The 28 .Nm pty 29 driver provides support for a pair of devices collectively known 30 as a 31 .Em pseudo-terminal . 32 The two devices comprising a pseudo-terminal are known as a 33 .Em manager 34 and a 35 .Em subsidiary . 36 The subsidiary device distinguishes between the 37 .Dv B0 baud rate and other baud rates specified in 38 the 39 .Fa c_cflag 40 field of the 41 .Vt termios 42 structure, and the 43 .Dv CLOCAL 44 flag in that member. 45 It does not support any of the other 46 .Xr termio 7I 47 device control functions specified by flags in the 48 .Fa c_cflag 49 field of the 50 .Vt termios 51 structure and by the 52 .Dv IGNBRK , 53 .Dv IGNPAR , 54 .Dv PARMRK , 55 or 56 .Dv INPCK 57 flags in the 58 .Fa c_iflag 59 field of the 60 .Vt termios 61 structure, as these functions apply only to asynchronous serial ports. 62 All other 63 .Xr termio 7I 64 functions must be performed by STREAMS modules pushed atop the driver; when a 65 subsidiary device is opened, the 66 .Xr ldterm 7M 67 and 68 .Xr ttcompat 7M 69 STREAMS modules are automatically pushed on top of the stream, providing the 70 standard 71 .Xr termio 7I 72 interface. 73 .Pp 74 Instead of having a hardware interface and associated hardware that supports 75 the terminal functions, the functions are implemented by another process 76 manipulating the manager device of the pseudo-terminal. 77 .Pp 78 The manager and the subsidiary devices of the pseudo-terminal are tightly 79 connected. 80 Any data written on the manager device is given to the subsidiary device as 81 input, as though it had been received from a hardware interface. 82 Any data written on the subsidiary terminal can be read from the manager device 83 .Pq "rather than being transmitted from a UAR" . 84 .Pp 85 The driver is statically configured to provide 48 pseudo-terminal pairs. 86 Software that requires dynamic pseudo-terminal devices, or a greater number 87 of devices, must be converted to use 88 .Xr ptm 7D . 89 .Sh IOCTLS 90 The standard set of 91 .Xr termio 7I 92 ioctls are supported by the subsidiary device. 93 None of the bits in the 94 .Fa c_cflag 95 field have any effect on the pseudo-terminal, except that if the baud rate is 96 set to 97 .Dv B0 , 98 it will appear to the process on the manager device as if the last process on 99 the subsidiary device had closed the line; thus, setting the baud rate to 100 .Dv B0 101 has the effect of 102 .Dq hanging up 103 the pseudo-terminal, just as it has the effect of 104 .Dq hanging up 105 a real terminal. 106 .Pp 107 There is no notion of 108 .Dq parity 109 on a pseudo-terminal, so none of the flags in the 110 .Fa c_iflag 111 field that control the processing of parity errors have any 112 effect. 113 Similarly, there is no notion of a 114 .Fa break , 115 so none of the flags that control the processing of breaks, and none of the 116 ioctls that generate breaks, have any effect. 117 .Pp 118 Input flow control is automatically performed; a process that attempts to write 119 to the manager device will be blocked if too much unconsumed data is buffered 120 on the subsidiary device. 121 The input flow control provided by the 122 .Dv IXOFF 123 flag in the 124 .Fa c_iflag 125 field is not supported. 126 .Pp 127 The delays specified in the 128 .Fa c_oflag 129 field are not supported. 130 .Pp 131 As there are no modems involved in a pseudo-terminal, the ioctls that return or 132 alter the state of modem control lines are silently ignored. 133 .Pp 134 A few special ioctls are provided on the manager devices of pseudo-terminals to 135 provide the functionality needed by applications programs to emulate real 136 hardware interfaces: 137 .Bl -tag -width Ds 138 .It Dv TIOCSTOP 139 The argument is ignored. 140 Output to the pseudo-terminal is suspended, as if a 141 .Sy STOP 142 character had been typed. 143 .It Dv TIOCSTART 144 The argument is ignored. 145 Output to the pseudo-terminal is restarted, as if a 146 .Sy START 147 character had been typed. 148 .It Dv TIOCPKT 149 The argument is a pointer to an 150 .Vt int . 151 If the value of the 152 .Vt int 153 is non-zero, 154 .Em packet 155 mode is enabled; if the value of the 156 .Vt int 157 is zero, packet mode is disabled. 158 When a pseudo-terminal is in packet mode, each subsequent 159 .Xr read 2 160 from the manager device will return data written on the subsidiary device 161 preceded by a zero byte 162 .Po 163 symbolically defined as 164 .Dv TIOCPKT_DATA 165 .Pc , 166 or a single byte reflecting control status information. 167 In the latter case, the byte is an inclusive-or of zero or more of the bits: 168 .Bl -tag -width Ds 169 .It Dv TIOCPKT_FLUSHREAD 170 Whenever the read queue for the terminal is flushed. 171 .It Dv TIOCPKT_FLUSHWRITE 172 Whenever the write queue for the terminal is flushed. 173 .It Dv TIOCPKT_STOP 174 Whenever output to the terminal is stopped using 175 .Sy ^S . 176 .It Dv TIOCPKT_START 177 Whenever output to the terminal is restarted. 178 .It Dv TIOCPKT_DOSTOP 179 Whenever 180 .Em XON/XOFF 181 flow control is enabled after being disabled; it is 182 considered 183 .Dq enabled 184 when the 185 .Dv IXON 186 flag in the 187 .Fa c_iflag 188 field is set, the 189 .Dv VSTOP 190 member of the 191 .Fa c_cc 192 array is 193 .Sy ^S 194 and the 195 .Dv VSTART 196 member of the 197 .Fa c_cc 198 array is 199 .Sy ^Q. 200 .It Dv TIOCPKT_NOSTOP 201 Whenever 202 .Em XON/XOFF 203 flow control is disabled after being enabled. 204 .El 205 .It Dv TIOCREMOTE 206 The argument is a pointer to an 207 .Vt int . 208 If the value of the 209 .Vt int 210 is non-zero, 211 .Em remote 212 mode is enabled; if the value of the 213 .Vt int 214 is zero, remote mode is disabled. 215 This mode can be enabled or disabled independently of packet mode. 216 When a pseudo-terminal is in remote mode, input to the subsidiary device of the 217 pseudo-terminal is flow controlled and not input edited (regardless of the mode 218 the subsidiary side of the pseudo-terminal). 219 .Pp 220 Each write to the manager device produces a record boundary for the process 221 reading the subsidiary device. 222 In normal usage, a write of data is like the data typed as a line on the 223 terminal; a write of 0 bytes is like typing an 224 .Sy EOF 225 character. 226 Note: this means that a process writing to a pseudo-terminal manager in remote 227 mode must keep track of line boundaries, and write only one line at a time to 228 the manager. 229 .Pp 230 If, for example, it were to buffer up several newline characters and write them 231 to the manager with one 232 .Xr write 2 , 233 it would appear to a process reading from the subsidiary as if a single line 234 containing several newline characters had been typed 235 .Po 236 as if, for example, a user had typed the literal next 237 .Pq Sy LNEXT 238 character before typing all but the last of those newline characters 239 .Pc . 240 Remote mode can be used when doing remote line editing in a window manager, or 241 whenever flow controlled input is required. 242 .El 243 .Sh FILES 244 .Bl -tag -width Pa 245 .It Pa /dev/pty[p-r][0-9a-f] 246 Pseudo-terminal manager devices. 247 .It Pa /dev/tty[p-r][0-9a-f] 248 Pseudo-terminal subsidiary devices. 249 .El 250 .Sh SEE ALSO 251 .Xr rlogin 1 , 252 .Xr rlogind 1M , 253 .Xr posix_openpty 3C , 254 .Xr ptm 7D , 255 .Xr termio 7I , 256 .Xr ldterm 7M , 257 .Xr ttcompat 7M 258 .Sh NOTES 259 This is a legacy device and should not be used by new software. 260 .Pp 261 It is apparently not possible to send an 262 .Sy EOT 263 by writing zero bytes in 264 .Dv TIOCREMOTE 265 mode.