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.\" 31.Dd December 31, 2017 32.Dt PTY 4 33.Os 34.Sh NAME 35.Nm pty 36.Nd pseudo terminal driver 37.Sh SYNOPSIS 38.Cd "pseudo-device pty" 39.Sh DESCRIPTION 40The 41.Nm 42driver provides support for a device-pair termed a 43.Em pseudo terminal . 44A pseudo terminal is a pair of character devices, a 45.Em master 46device and a 47.Em slave 48device. The slave device provides to a process 49an interface identical 50to that described in 51.Xr tty 4 . 52However, whereas all other devices which provide the 53interface described in 54.Xr tty 4 55have a hardware device of some sort behind them, the slave 56device has, instead, another process manipulating 57it through the master half of the pseudo terminal. 58That is, anything written on the master device is 59given to the slave device as input and anything written 60on the slave device is presented as input on the master 61device. 62.Pp 63The following 64.Xr ioctl 2 65calls apply only to pseudo terminals: 66.Bl -tag -width ".Dv TIOCREMOTE" 67.It Dv TIOCSTOP 68Stops output to a terminal (e.g. like typing 69.Ql ^S ) . 70Takes 71no parameter. 72.It Dv TIOCSTART 73Restarts output (stopped by 74.Dv TIOCSTOP 75or by typing 76.Ql ^S ) . 77Takes no parameter. 78.It Dv TIOCPKT 79Enable/disable 80.Em packet 81mode. Packet mode is enabled by specifying (by reference) 82a nonzero parameter and disabled by specifying (by reference) 83a zero parameter. When applied to the master side of a pseudo 84terminal, each subsequent 85.Xr read 2 86from the terminal will return data written on the slave part of 87the pseudo terminal preceded by a zero byte (symbolically 88defined as 89.Dv TIOCPKT_DATA ) , 90or a single byte reflecting control 91status information. In the latter case, the byte is an inclusive-or 92of zero or more of the bits: 93.Bl -tag -width TIOCPKT_FLUSHWRITE 94.It Dv TIOCPKT_FLUSHREAD 95whenever the read queue for the terminal is flushed. 96.It Dv TIOCPKT_FLUSHWRITE 97whenever the write queue for the terminal is flushed. 98.It Dv TIOCPKT_STOP 99whenever output to the terminal is stopped a la 100.Ql ^S . 101.It Dv TIOCPKT_START 102whenever output to the terminal is restarted. 103.It Dv TIOCPKT_DOSTOP 104whenever 105.Em t_stopc 106is 107.Ql ^S 108and 109.Em t_startc 110is 111.Ql ^Q . 112.It Dv TIOCPKT_NOSTOP 113whenever the start and stop characters are not 114.Ql ^S/^Q . 115.Pp 116While this mode is in use, the presence of control status information 117to be read from the master side may be detected by a 118.Xr select 2 119for exceptional conditions. 120.Pp 121This mode is used by 122.Xr rlogin 1 Pq Pa net/bsdrcmds 123and 124.Xr rlogind 8 Pq Pa net/bsdrcmds 125to implement a remote-echoed, locally 126.Ql ^S/^Q 127flow-controlled 128remote login with proper back-flushing of output; it can be 129used by other similar programs. 130.El 131.It Dv TIOCUCNTL 132Enable/disable a mode that allows a small number of simple user 133.Xr ioctl 2 134commands to be passed through the pseudo-terminal, 135using a protocol similar to that of 136.Dv TIOCPKT . 137The 138.Dv TIOCUCNTL 139and 140.Dv TIOCPKT 141modes are mutually exclusive. 142This mode is enabled from the master side of a pseudo terminal 143by specifying (by reference) 144a nonzero parameter and disabled by specifying (by reference) 145a zero parameter. 146Each subsequent 147.Xr read 2 148from the master side will return data written on the slave part of 149the pseudo terminal preceded by a zero byte, 150or a single byte reflecting a user control operation on the slave side. 151A user control command consists of a special 152.Xr ioctl 2 153operation with no data; the command is given as 154.Dv UIOCCMD Ns (n) , 155where 156.Ar n 157is a number in the range 1-255. 158The operation value 159.Ar n 160will be received as a single byte on the next 161.Xr read 2 162from the master side. 163The 164.Xr ioctl 2 165.Dv UIOCCMD Ns (0) 166is a no-op that may be used to probe for 167the existence of this facility. 168As with 169.Dv TIOCPKT 170mode, command operations may be detected with a 171.Xr select 2 172for exceptional conditions. 173.It Dv TIOCREMOTE 174A mode for the master half of a pseudo terminal, independent 175of 176.Dv TIOCPKT . 177This mode causes input to the pseudo terminal 178to be flow controlled and not input edited (regardless of the 179terminal mode). Each write to the control terminal produces 180a record boundary for the process reading the terminal. In 181normal usage, a write of data is like the data typed as a line 182on the terminal; a write of 0 bytes is like typing an end-of-file 183character. 184.Dv TIOCREMOTE 185can be used when doing remote line 186editing in a window manager, or whenever flow controlled input 187is required. 188.El 189.Sh FILES 190.Bl -tag -width /dev/tty[p-sP-S][0-9a-v]x -compact 191.It Pa /dev/pty[p-sP-S][0-9a-v] 192master pseudo terminals 193.It Pa /dev/tty[p-sP-S][0-9a-v] 194slave pseudo terminals 195.El 196.Sh DIAGNOSTICS 197None. 198.Sh SEE ALSO 199.Xr tty 4 200.Sh HISTORY 201The 202.Nm 203driver appeared in 204.Bx 4.2 . 205