1.\" Copyright (c) 1983, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)pty.4 8.2 (Berkeley) 11/30/93 33.\" 34.Dd November 30, 1993 35.Dt PTY 4 36.Os BSD 4.2 37.Sh NAME 38.Nm pty 39.Nd pseudo terminal driver 40.Sh SYNOPSIS 41.Cd "pseudo-device pty" Op Ar count 42.Sh DESCRIPTION 43The 44.Nm pty 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. The slave device provides to a process 52an interface identical 53to that described 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 32. 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. Packet mode is enabled by specifying (by reference) 91a nonzero parameter and disabled by specifying (by reference) 92a zero parameter. When 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 100status information. In 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.El 140.It Dv TIOCUCNTL 141Enable/disable a mode that allows a small number of simple user 142.Xr ioctl 2 143commands to be passed through the pseudo-terminal, 144using a protocol similar to that of 145.Dv TIOCPKT . 146The 147.Dv TIOCUCNTL 148and 149.Dv TIOCPKT 150modes are mutually exclusive. 151This mode is enabled from the master side of a pseudo terminal 152by specifying (by reference) 153a nonzero parameter and disabled by specifying (by reference) 154a zero parameter. 155Each subsequent 156.Xr read 2 157from the master side will return data written on the slave part of 158the pseudo terminal preceded by a zero byte, 159or a single byte reflecting a user control operation on the slave side. 160A user control command consists of a special 161.Xr ioctl 2 162operation with no data; the command is given as 163.Dv UIOCCMD Ns (n) , 164where 165.Ar n 166is a number in the range 1-255. 167The operation value 168.Ar n 169will be received as a single byte on the next 170.Xr read 2 171from the master side. 172The 173.Xr ioctl 2 174.Dv UIOCCMD Ns (0) 175is a no-op that may be used to probe for 176the existence of this facility. 177As with 178.Dv TIOCPKT 179mode, command operations may be detected with a 180.Xr select 2 181for exceptional conditions. 182.It Dv TIOCREMOTE 183A mode for the master half of a pseudo terminal, independent 184of 185.Dv TIOCPKT . 186This mode causes input to the pseudo terminal 187to be flow controlled and not input edited (regardless of the 188terminal mode). Each write to the control terminal produces 189a record boundary for the process reading the terminal. In 190normal usage, a write of data is like the data typed as a line 191on the terminal; a write of 0 bytes is like typing an end-of-file 192character. 193.Dv TIOCREMOTE 194can be used when doing remote line 195editing in a window manager, or whenever flow controlled input 196is required. 197.El 198.Sh FILES 199.Bl -tag -width /dev/tty[p-sP-S][0-9a-v]x -compact 200.It Pa /dev/pty[p-sP-S][0-9a-v] 201master pseudo terminals 202.It Pa /dev/tty[p-sP-S][0-9a-v] 203slave pseudo terminals 204.El 205.Sh DIAGNOSTICS 206None. 207.Sh HISTORY 208The 209.Nm 210driver appeared in 211.Bx 4.2 . 212