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