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