1.\" $NetBSD: pty.4,v 1.15 2013/12/01 00:17:14 christos Exp $ 2.\" 3.\" Copyright (c) 1983, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)pty.4 8.2 (Berkeley) 11/30/93 31.\" 32.Dd November 30, 2013 33.Dt PTY 4 34.Os 35.Sh NAME 36.Nm pty 37.Nd pseudo terminal driver 38.Sh SYNOPSIS 39.Cd pseudo-device pty 40.Sh DESCRIPTION 41The 42.Nm 43driver provides support for a device-pair termed a 44.Em pseudo terminal . 45A pseudo terminal is a pair of character devices, a 46.Em master 47device and a 48.Em slave 49device. 50The slave device provides to a process an interface identical to 51that described in 52.Xr tty 4 . 53However, whereas all other devices which provide the interface described in 54.Xr tty 4 55have a hardware device of some sort behind them, the slave device 56has, instead, another process manipulating it through the master 57half of the pseudo terminal. 58That is, anything written on the master device is given to the 59slave device as input and anything written on the slave device is 60presented as input on the master device. 61.Pp 62Pseudo terminal pairs are allocated on 63as-needed basis, maximum number of them is controlled via 64.Em kern.maxptys 65sysctl (defaults to 992). 66.Pp 67The following 68.Xr ioctl 2 69calls apply only to pseudo terminals: 70.Bl -tag -width TIOCREMOTE 71.It Dv TIOCEXT 72Enable/disable 73.Dq "external processing" . 74This affects delivery of 75.Dv TIOCPKT_IOCTL 76packets. 77External processing is enabled by specifying (by reference) a nonzero 78.Vt int 79parameter and disabled by specifying (by reference) a zero 80.Vt int 81parameter. 82.Pp 83.Dv TIOCEXT 84is reset to its default (disabled) when the slave closes the 85.Nm . 86.It Dv TIOCSTOP 87Stops output to a terminal (e.g. like typing 88.Ql ^S ) . 89Takes 90no parameter. 91.It Dv TIOCSTART 92Restarts output (stopped by 93.Dv TIOCSTOP 94or by typing 95.Ql ^S ) . 96Takes no parameter. 97.It Dv TIOCPKT 98Enable/disable 99.Em packet 100mode. 101Packet mode is enabled by specifying (by reference) a nonzero 102.Vt int 103parameter and disabled by specifying (by reference) a zero 104.Vt int 105parameter. 106When applied to the master side of a pseudo 107terminal, each subsequent 108.Xr read 2 109from the terminal will return data written on the slave part of 110the pseudo terminal preceded by a zero byte (symbolically 111defined as 112.Dv TIOCPKT_DATA ) , 113or a single byte reflecting control status information. 114In the latter case, the byte is an inclusive-or 115of zero or more of the bits: 116.Bl -tag -width TIOCPKT_FLUSHWRITE 117.It Dv TIOCPKT_FLUSHREAD 118whenever the read queue for the terminal is flushed. 119.It Dv TIOCPKT_FLUSHWRITE 120whenever the write queue for the terminal is flushed. 121.It Dv TIOCPKT_STOP 122whenever output to the terminal is stopped a la 123.Ql ^S . 124.It Dv TIOCPKT_START 125whenever output to the terminal is restarted. 126.It Dv TIOCPKT_DOSTOP 127whenever 128.Em t_stopc 129is 130.Ql ^S 131and 132.Em t_startc 133is 134.Ql ^Q . 135.It Dv TIOCPKT_NOSTOP 136whenever the start and stop characters are not 137.Ql ^S/^Q . 138.Pp 139While this mode is in use, the presence of control status information 140to be read from the master side may be detected by a 141.Xr select 2 142for exceptional conditions. 143.Pp 144This mode is used by 145.Xr rlogin 1 146and 147.Xr rlogind 8 148to implement a remote-echoed, locally 149.Ql ^S/^Q 150flow-controlled 151remote login with proper back-flushing of output; it can be 152used by other similar programs. 153.It Dv TIOCPKT_IOCTL 154When this bit is set, the slave has changed the 155.Xr termios 4 156structure (TTY state), 157and the remainder of the data read from 158the master side of the 159.Nm 160is the new 161.Xr termios 4 162structure. 163The master side of the 164.Nm 165can also use 166.Xr tcgetattr 3 167to read the new 168.Xr termios 4 169structure. 170.Pp 171The master will not read packets with the bit 172.Dv TIOCPKT_IOCTL 173set until it has activated 174.Dq "external processing" 175using 176.Dv TIOCEXT . 177.Pp 178This is used by 179.Xr telnetd 8 180to implement TELNET "line mode" - it allows the 181.Xr telnetd 8 182to detect 183.Xr tty 4 184state changes by the slave, and negotiate the appropriate TELNET 185protocol equivalents with the remote peer. 186.El 187.It Dv TIOCUCNTL 188Enable/disable a mode that allows a small number of simple user 189.Xr ioctl 2 190commands to be passed through the pseudo-terminal, 191using a protocol similar to that of 192.Dv TIOCPKT . 193The 194.Dv TIOCUCNTL 195and 196.Dv TIOCPKT 197modes are mutually exclusive. 198This mode is enabled from the master side of a pseudo terminal 199by specifying (by reference) 200a nonzero 201.Vt int 202parameter and disabled by specifying (by reference) 203a zero 204.Vt int 205parameter. 206Each subsequent 207.Xr read 2 208from the master side will return data written on the slave part of 209the pseudo terminal preceded by a zero byte, 210or a single byte reflecting a user control operation on the slave side. 211A user control command consists of a special 212.Xr ioctl 2 213operation with no data; the command is given as 214.Dv UIOCCMD Ns (n) , 215where 216.Ar n 217is a number in the range 1-255. 218The operation value 219.Ar n 220will be received as a single byte on the next 221.Xr read 2 222from the master side. 223The 224.Xr ioctl 2 225.Dv UIOCCMD Ns (0) 226is a no-op that may be used to probe for 227the existence of this facility. 228As with 229.Dv TIOCPKT 230mode, command operations may be detected with a 231.Xr select 2 232for exceptional conditions. 233.It Dv TIOCREMOTE 234A mode for the master half of a pseudo terminal, independent 235of 236.Dv TIOCPKT . 237This mode causes input to the pseudo terminal to be flow controlled 238and not input edited (regardless of the terminal mode). 239Each write to the control terminal produces a record boundary for 240the process reading the terminal. 241In normal usage, a write of data is like the data typed as a line 242on the terminal; a write of 0 bytes is like typing an end-of-file 243character. 244.Dv TIOCREMOTE 245can be used when doing remote line 246editing in a window manager, or whenever flow controlled input 247is required. 248.El 249.Sh FILES 250.Bl -tag -width /dev/tty[p-zP-T][0-9a-zA-Z]x -compact 251.It Pa /dev/pty[p-zP-T][0-9a-zA-Z] 252master pseudo terminals 253.It Pa /dev/tty[p-zP-T][0-9a-zA-Z] 254slave pseudo terminals 255.El 256.Sh DIAGNOSTICS 257None. 258.Sh SEE ALSO 259.Xr ioctl 2 , 260.Xr read 2 , 261.Xr select 2 , 262.Xr write 2 , 263.Xr openpty 3 , 264.Xr tty 4 265.Sh HISTORY 266The 267.Nm 268driver appeared in 269.Bx 4.2 . 270