1.\" $OpenBSD: pty.4,v 1.10 2003/06/02 23:30:12 millert Exp $ 2.\" $NetBSD: pty.4,v 1.4 1998/03/21 03:14:30 fair Exp $ 3.\" 4.\" Copyright (c) 1983, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)pty.4 8.2 (Berkeley) 11/30/93 32.\" 33.Dd November 30, 1993 34.Dt PTY 4 35.Os 36.Sh NAME 37.Nm pty 38.Nd pseudo terminal driver 39.Sh SYNOPSIS 40.Nm pseudo-device pty 41.Op Ar count 42.Sh DESCRIPTION 43The 44.Nm 45driver provides support for a device-pair termed a 46.Em pseudo terminal . 47A pseudo terminal is a pair of character devices, a 48.Em master 49device and a 50.Em slave 51device. 52The slave device provides to a process an interface identical to that 53described in 54.Xr tty 4 . 55However, whereas all other devices which provide the 56interface described in 57.Xr tty 4 58have a hardware device of some sort behind them, the slave 59device has, instead, another process manipulating 60it through the master half of the pseudo terminal. 61That is, anything written on the master device is 62given to the slave device as input and anything written 63on the slave device is presented as input on the master 64device. 65.Pp 66In configuring, if an optional 67.Ar count 68is given in 69the specification, that number of pseudo terminal pairs are configured; 70the default count is 64. 71.Pp 72The following 73.Xr ioctl 2 74calls apply only to pseudo terminals: 75.Bl -tag -width TIOCREMOTE 76.It Dv TIOCSTOP 77Stops output to a terminal (e.g., like typing 78.Ql ^S ) . 79Takes 80no parameter. 81.It Dv TIOCSTART 82Restarts output (stopped by 83.Dv TIOCSTOP 84or by typing 85.Ql ^S ) . 86Takes no parameter. 87.It Dv TIOCPKT 88Enable/disable 89.Em packet 90mode. 91Packet mode is enabled by specifying (by reference) a non-zero parameter 92and disabled by specifying (by reference) a zero parameter. 93When applied to the master side of a pseudo terminal, 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 100status information. 101In the latter case, the byte is an inclusive-or of 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 132and 133.Xr rlogind 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 205to be flow controlled and not input edited (regardless of the terminal mode). 206Each write to the control terminal produces a record boundary for the process 207reading 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-r][0-9a-f]x -compact 218.It Pa /dev/pty[p-r][0-9a-f] 219master pseudo terminals 220.It Pa /dev/tty[p-r][0-9a-f] 221slave pseudo terminals 222.El 223.Sh SEE ALSO 224.Xr tty 4 225.Sh HISTORY 226The 227.Nm 228driver appeared in 229.Bx 4.2 . 230