1.\" $NetBSD: pty.4,v 1.14 2011/02/01 18:01:06 wiz 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 February 1, 2011 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 Op Ar count 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 62In configuring, if an optional 63.Ar count 64is given in 65the specification, that number of pseudo terminal pairs is initially configured; 66the default count is 16. 67Additional pseudo terminal pairs are allocated on 68as-needed basis, maximum number of them is controlled via 69.Em kern.maxptys 70sysctl (defaults to 992). 71.Pp 72The following 73.Xr ioctl 2 74calls apply only to pseudo terminals: 75.Bl -tag -width TIOCREMOTE 76.It Dv TIOCEXT 77Enable/disable 78.Dq "external processing" . 79This affects delivery of 80.Dv TIOCPKT_IOCTL 81packets. 82External processing is enabled by specifying (by reference) a nonzero 83.Vt int 84parameter and disabled by specifying (by reference) a zero 85.Vt int 86parameter. 87.Pp 88.Dv TIOCEXT 89is reset to its default (disabled) when the slave closes the 90.Nm . 91.It Dv TIOCSTOP 92Stops output to a terminal (e.g. like typing 93.Ql ^S ) . 94Takes 95no parameter. 96.It Dv TIOCSTART 97Restarts output (stopped by 98.Dv TIOCSTOP 99or by typing 100.Ql ^S ) . 101Takes no parameter. 102.It Dv TIOCPKT 103Enable/disable 104.Em packet 105mode. 106Packet mode is enabled by specifying (by reference) a nonzero 107.Vt int 108parameter and disabled by specifying (by reference) a zero 109.Vt int 110parameter. 111When applied to the master side of a pseudo 112terminal, each subsequent 113.Xr read 2 114from the terminal will return data written on the slave part of 115the pseudo terminal preceded by a zero byte (symbolically 116defined as 117.Dv TIOCPKT_DATA ) , 118or a single byte reflecting control status information. 119In the latter case, the byte is an inclusive-or 120of zero or more of the bits: 121.Bl -tag -width TIOCPKT_FLUSHWRITE 122.It Dv TIOCPKT_FLUSHREAD 123whenever the read queue for the terminal is flushed. 124.It Dv TIOCPKT_FLUSHWRITE 125whenever the write queue for the terminal is flushed. 126.It Dv TIOCPKT_STOP 127whenever output to the terminal is stopped a la 128.Ql ^S . 129.It Dv TIOCPKT_START 130whenever output to the terminal is restarted. 131.It Dv TIOCPKT_DOSTOP 132whenever 133.Em t_stopc 134is 135.Ql ^S 136and 137.Em t_startc 138is 139.Ql ^Q . 140.It Dv TIOCPKT_NOSTOP 141whenever the start and stop characters are not 142.Ql ^S/^Q . 143.Pp 144While this mode is in use, the presence of control status information 145to be read from the master side may be detected by a 146.Xr select 2 147for exceptional conditions. 148.Pp 149This mode is used by 150.Xr rlogin 1 151and 152.Xr rlogind 8 153to implement a remote-echoed, locally 154.Ql ^S/^Q 155flow-controlled 156remote login with proper back-flushing of output; it can be 157used by other similar programs. 158.It Dv TIOCPKT_IOCTL 159When this bit is set, the slave has changed the 160.Xr termios 4 161structure (TTY state), 162and the remainder of the data read from 163the master side of the 164.Nm 165is the new 166.Xr termios 4 167structure. 168The master side of the 169.Nm 170can also use 171.Xr tcgetattr 3 172to read the new 173.Xr termios 4 174structure. 175.Pp 176The master will not read packets with the bit 177.Dv TIOCPKT_IOCTL 178set until it has activated 179.Dq "external processing" 180using 181.Dv TIOCEXT . 182.Pp 183This is used by 184.Xr telnetd 8 185to implement TELNET "line mode" - it allows the 186.Xr telnetd 8 187to detect 188.Xr tty 4 189state changes by the slave, and negotiate the appropriate TELNET 190protocol equivalents with the remote peer. 191.El 192.It Dv TIOCUCNTL 193Enable/disable a mode that allows a small number of simple user 194.Xr ioctl 2 195commands to be passed through the pseudo-terminal, 196using a protocol similar to that of 197.Dv TIOCPKT . 198The 199.Dv TIOCUCNTL 200and 201.Dv TIOCPKT 202modes are mutually exclusive. 203This mode is enabled from the master side of a pseudo terminal 204by specifying (by reference) 205a nonzero 206.Vt int 207parameter and disabled by specifying (by reference) 208a zero 209.Vt int 210parameter. 211Each subsequent 212.Xr read 2 213from the master side will return data written on the slave part of 214the pseudo terminal preceded by a zero byte, 215or a single byte reflecting a user control operation on the slave side. 216A user control command consists of a special 217.Xr ioctl 2 218operation with no data; the command is given as 219.Dv UIOCCMD Ns (n) , 220where 221.Ar n 222is a number in the range 1-255. 223The operation value 224.Ar n 225will be received as a single byte on the next 226.Xr read 2 227from the master side. 228The 229.Xr ioctl 2 230.Dv UIOCCMD Ns (0) 231is a no-op that may be used to probe for 232the existence of this facility. 233As with 234.Dv TIOCPKT 235mode, command operations may be detected with a 236.Xr select 2 237for exceptional conditions. 238.It Dv TIOCREMOTE 239A mode for the master half of a pseudo terminal, independent 240of 241.Dv TIOCPKT . 242This mode causes input to the pseudo terminal to be flow controlled 243and not input edited (regardless of the terminal mode). 244Each write to the control terminal produces a record boundary for 245the process reading the terminal. 246In normal usage, a write of data is like the data typed as a line 247on the terminal; a write of 0 bytes is like typing an end-of-file 248character. 249.Dv TIOCREMOTE 250can be used when doing remote line 251editing in a window manager, or whenever flow controlled input 252is required. 253.El 254.Sh FILES 255.Bl -tag -width /dev/tty[p-zP-T][0-9a-zA-Z]x -compact 256.It Pa /dev/pty[p-zP-T][0-9a-zA-Z] 257master pseudo terminals 258.It Pa /dev/tty[p-zP-T][0-9a-zA-Z] 259slave pseudo terminals 260.El 261.Sh DIAGNOSTICS 262None. 263.Sh SEE ALSO 264.Xr ioctl 2 , 265.Xr read 2 , 266.Xr select 2 , 267.Xr write 2 , 268.Xr openpty 3 , 269.Xr tty 4 270.Sh HISTORY 271The 272.Nm 273driver appeared in 274.Bx 4.2 . 275