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. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)pty.4 8.2 (Berkeley) 11/30/93 29.\" $FreeBSD: src/share/man/man4/pty.4,v 1.8.2.3 2001/08/17 13:08:39 ru Exp $ 30.\" $DragonFly: src/share/man/man4/pty.4,v 1.2 2003/06/17 04:36:59 dillon Exp $ 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" 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. The slave device provides to a process 50an interface identical 51to that described in 52.Xr tty 4 . 53However, whereas all other devices which provide the 54interface described in 55.Xr tty 4 56have a hardware device of some sort behind them, the slave 57device has, instead, another process manipulating 58it through the master half of the pseudo terminal. 59That is, anything written on the master device is 60given to the slave device as input and anything written 61on the slave device is presented as input on the master 62device. 63.Pp 64The following 65.Xr ioctl 2 66calls apply only to pseudo terminals: 67.Bl -tag -width ".Dv TIOCREMOTE" 68.It Dv TIOCSTOP 69Stops output to a terminal (e.g. like typing 70.Ql ^S ) . 71Takes 72no parameter. 73.It Dv TIOCSTART 74Restarts output (stopped by 75.Dv TIOCSTOP 76or by typing 77.Ql ^S ) . 78Takes no parameter. 79.It Dv TIOCPKT 80Enable/disable 81.Em packet 82mode. Packet mode is enabled by specifying (by reference) 83a nonzero parameter and disabled by specifying (by reference) 84a zero parameter. When applied to the master side of a pseudo 85terminal, each subsequent 86.Xr read 2 87from the terminal will return data written on the slave part of 88the pseudo terminal preceded by a zero byte (symbolically 89defined as 90.Dv TIOCPKT_DATA ) , 91or a single byte reflecting control 92status information. In the latter case, the byte is an inclusive-or 93of zero or more of the bits: 94.Bl -tag -width TIOCPKT_FLUSHWRITE 95.It Dv TIOCPKT_FLUSHREAD 96whenever the read queue for the terminal is flushed. 97.It Dv TIOCPKT_FLUSHWRITE 98whenever the write queue for the terminal is flushed. 99.It Dv TIOCPKT_STOP 100whenever output to the terminal is stopped a la 101.Ql ^S . 102.It Dv TIOCPKT_START 103whenever output to the terminal is restarted. 104.It Dv TIOCPKT_DOSTOP 105whenever 106.Em t_stopc 107is 108.Ql ^S 109and 110.Em t_startc 111is 112.Ql ^Q . 113.It Dv TIOCPKT_NOSTOP 114whenever the start and stop characters are not 115.Ql ^S/^Q . 116.Pp 117While this mode is in use, the presence of control status information 118to be read from the master side may be detected by a 119.Xr select 2 120for exceptional conditions. 121.Pp 122This mode is used by 123.Xr rlogin 1 124and 125.Xr rlogind 8 126to implement a remote-echoed, locally 127.Ql ^S/^Q 128flow-controlled 129remote login with proper back-flushing of output; it can be 130used by other similar programs. 131.El 132.It Dv TIOCUCNTL 133Enable/disable a mode that allows a small number of simple user 134.Xr ioctl 2 135commands to be passed through the pseudo-terminal, 136using a protocol similar to that of 137.Dv TIOCPKT . 138The 139.Dv TIOCUCNTL 140and 141.Dv TIOCPKT 142modes are mutually exclusive. 143This mode is enabled from the master side of a pseudo terminal 144by specifying (by reference) 145a nonzero parameter and disabled by specifying (by reference) 146a zero parameter. 147Each subsequent 148.Xr read 2 149from the master side will return data written on the slave part of 150the pseudo terminal preceded by a zero byte, 151or a single byte reflecting a user control operation on the slave side. 152A user control command consists of a special 153.Xr ioctl 2 154operation with no data; the command is given as 155.Dv UIOCCMD Ns (n) , 156where 157.Ar n 158is a number in the range 1-255. 159The operation value 160.Ar n 161will be received as a single byte on the next 162.Xr read 2 163from the master side. 164The 165.Xr ioctl 2 166.Dv UIOCCMD Ns (0) 167is a no-op that may be used to probe for 168the existence of this facility. 169As with 170.Dv TIOCPKT 171mode, command operations may be detected with a 172.Xr select 2 173for exceptional conditions. 174.It Dv TIOCREMOTE 175A mode for the master half of a pseudo terminal, independent 176of 177.Dv TIOCPKT . 178This mode causes input to the pseudo terminal 179to be flow controlled and not input edited (regardless of the 180terminal mode). Each write to the control terminal produces 181a record boundary for the process reading the terminal. In 182normal usage, a write of data is like the data typed as a line 183on the terminal; a write of 0 bytes is like typing an end-of-file 184character. 185.Dv TIOCREMOTE 186can be used when doing remote line 187editing in a window manager, or whenever flow controlled input 188is required. 189.El 190.Sh FILES 191.Bl -tag -width /dev/tty[p-sP-S][0-9a-v]x -compact 192.It Pa /dev/pty[p-sP-S][0-9a-v] 193master pseudo terminals 194.It Pa /dev/tty[p-sP-S][0-9a-v] 195slave pseudo terminals 196.El 197.Sh DIAGNOSTICS 198None. 199.Sh SEE ALSO 200.Xr tty 4 201.Sh HISTORY 202The 203.Nm 204driver appeared in 205.Bx 4.2 . 206