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.3 (Berkeley) 12/08/94 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 to a process 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.Dv TIOCSIG 63Sends the specified signal to the process group members of the 64pseudo terminal that have it as their controlling terminal. 65.It Dv TIOCPKT 66Enable/disable 67.Em packet 68mode. Packet mode is enabled by specifying (by reference) 69a nonzero parameter and disabled by specifying (by reference) 70a zero parameter. When applied to the master side of a pseudo 71terminal, each subsequent 72.Xr read 73from the terminal will return data written on the slave part of 74the pseudo terminal preceded by a zero byte (symbolically 75defined as 76.Dv TIOCPKT_DATA ) , 77or a single byte reflecting control 78status information. In the latter case, the byte is an inclusive-or 79of zero or more of the bits: 80.Bl -tag -width TIOCPKT_FLUSHWRITE 81.It Dv TIOCPKT_FLUSHREAD 82whenever the read queue for the terminal is flushed. 83.It Dv TIOCPKT_FLUSHWRITE 84whenever the write queue for the terminal is flushed. 85.It Dv TIOCPKT_STOP 86whenever output to the terminal is stopped a la 87.Ql ^S . 88.It Dv TIOCPKT_START 89whenever output to the terminal is restarted. 90.It Dv TIOCPKT_DOSTOP 91whenever 92.Em t_stopc 93is 94.Ql ^S 95and 96.Em t_startc 97is 98.Ql ^Q . 99.It Dv TIOCPKT_NOSTOP 100whenever the start and stop characters are not 101.Ql ^S/^Q . 102.Pp 103While this mode is in use, the presence of control status information 104to be read from the master side may be detected by a 105.Xr select 2 106for exceptional conditions. 107.Pp 108This mode is used by 109.Xr rlogin 1 110and 111.Xr rlogind 8 112to implement a remote-echoed, locally 113.Ql ^S/^Q 114flow-controlled 115remote login with proper back-flushing of output; it can be 116used by other similar programs. 117.El 118.It Dv TIOCUCNTL 119Enable/disable a mode that allows a small number of simple user 120.Xr ioctl 121commands to be passed through the pseudo-terminal, 122using a protocol similar to that of 123.Dv TIOCPKT . 124The 125.Dv TIOCUCNTL 126and 127.Dv TIOCPKT 128modes are mutually exclusive. 129This mode is enabled from the master side of a pseudo terminal 130by specifying (by reference) 131a nonzero parameter and disabled by specifying (by reference) 132a zero parameter. 133Each subsequent 134.Xr read 135from the master side will return data written on the slave part of 136the pseudo terminal preceded by a zero byte, 137or a single byte reflecting a user control operation on the slave side. 138A user control command consists of a special 139.Xr ioctl 140operation with no data; the command is given as 141.Dv UIOCCMD Ns (n) , 142where 143.Ar n 144is a number in the range 1-255. 145The operation value 146.Ar n 147will be received as a single byte on the next 148.Xr read 149from the master side. 150The 151.Xr ioctl 152.Dv UIOCCMD Ns (0) 153is a no-op that may be used to probe for 154the existence of this facility. 155As with 156.Dv TIOCPKT 157mode, command operations may be detected with a 158.Xr select 159for exceptional conditions. 160.It Dv TIOCREMOTE 161A mode for the master half of a pseudo terminal, independent 162of 163.Dv TIOCPKT . 164This mode causes input to the pseudo terminal 165to be flow controlled and not input edited (regardless of the 166terminal mode). Each write to the control terminal produces 167a record boundary for the process reading the terminal. In 168normal usage, a write of data is like the data typed as a line 169on the terminal; a write of 0 bytes is like typing an end-of-file 170character. 171.Dv TIOCREMOTE 172can be used when doing remote line 173editing in a window manager, or whenever flow controlled input 174is required. 175.El 176.Sh FILES 177.Bl -tag -width /dev/tty[p-r][0-9a-f]x -compact 178.It Pa /dev/pty[p-r][0-9a-f] 179master pseudo terminals 180.It Pa /dev/tty[p-r][0-9a-f] 181slave pseudo terminals 182.El 183.Sh DIAGNOSTICS 184None. 185.Sh HISTORY 186The 187.Nm 188driver appeared in 189.Bx 4.2 . 190