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