1.\" $OpenBSD: pty.4,v 1.19 2007/05/31 19:19:51 jmc Exp $ 2.\" $NetBSD: pty.4,v 1.4 1998/03/21 03:14:30 fair Exp $ 3.\" 4.\" Copyright (c) 1983, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)pty.4 8.2 (Berkeley) 11/30/93 32.\" 33.Dd $Mdocdate: May 31 2007 $ 34.Dt PTY 4 35.Os 36.Sh NAME 37.Nm pty 38.Nd pseudo terminal driver 39.Sh SYNOPSIS 40.Cd "pseudo-device pty" Op Ar count 41.Sh DESCRIPTION 42The 43.Nm 44driver provides support for a device-pair termed a 45.Em pseudo terminal . 46A pseudo terminal is a pair of character devices, a 47.Em master 48device and a 49.Em slave 50device. 51The slave device provides to a process an interface identical to that 52described in 53.Xr tty 4 . 54However, whereas all other devices which provide the 55interface described in 56.Xr tty 4 57have a hardware device of some sort behind them, the slave 58device has, instead, another process manipulating 59it through the master half of the pseudo terminal. 60That is, anything written on the master device is 61given to the slave device as input and anything written 62on the slave device is presented as input on the master 63device. 64.Pp 65In configuring, if an optional 66.Ar count 67is given in 68the specification, space for that number of pseudo terminal pairs is 69preallocated. 70If the count is missing or is less than 2, a default count of 8 is used. 71This is not a hard limit--space for additional pseudo terminal pairs 72is allocated on demand up to the limit imposed by the 73.Li kern.tty.maxptys 74.Xr sysctl 8 75(992 by default). 76.Pp 77The following 78.Xr ioctl 2 79calls apply only to pseudo terminals: 80.Bl -tag -width TIOCREMOTE 81.It Dv TIOCSTOP 82Stops output to a terminal (e.g., like typing 83.Ql ^S ) . 84Takes 85no parameter. 86.It Dv TIOCSTART 87Restarts output (stopped by 88.Dv TIOCSTOP 89or by typing 90.Ql ^S ) . 91Takes no parameter. 92.It Dv TIOCPKT 93Enable/disable 94.Em packet 95mode. 96Packet mode is enabled by specifying (by reference) a non-zero parameter 97and disabled by specifying (by reference) a zero parameter. 98When applied to the master side of a pseudo terminal, each subsequent 99.Xr read 2 100from the terminal will return data written on the slave part of 101the pseudo terminal preceded by a zero byte (symbolically 102defined as 103.Dv TIOCPKT_DATA ) , 104or a single byte reflecting control 105status information. 106In the latter case, the byte is an inclusive-or of zero or more of the bits: 107.Bl -tag -width TIOCPKT_FLUSHWRITE 108.It Dv TIOCPKT_FLUSHREAD 109whenever the read queue for the terminal is flushed. 110.It Dv TIOCPKT_FLUSHWRITE 111whenever the write queue for the terminal is flushed. 112.It Dv TIOCPKT_STOP 113whenever output to the terminal is stopped a la 114.Ql ^S . 115.It Dv TIOCPKT_START 116whenever output to the terminal is restarted. 117.It Dv TIOCPKT_DOSTOP 118whenever 119.Em t_stopc 120is 121.Ql ^S 122and 123.Em t_startc 124is 125.Ql ^Q . 126.It Dv TIOCPKT_NOSTOP 127whenever the start and stop characters are not 128.Ql ^S/^Q . 129.Pp 130While this mode is in use, the presence of control status information 131to be read from the master side may be detected by a 132.Xr select 2 133for exceptional conditions. 134.Pp 135This mode is used by 136.Xr rlogin 137and 138.Xr rlogind 139to implement a remote-echoed, locally 140.Ql ^S/^Q 141flow-controlled 142remote login with proper back-flushing of output; it can be 143used by other similar programs. 144.It Dv TIOCPKT_IOCTL 145When this bit is set, the slave has changed the 146.Xr termios 4 147structure (TTY state), and the remainder of the data read from 148the master side of the 149.Nm 150is a copy of the new 151.Xr termios 4 152structure. 153.Pp 154This is used by telnet daemons to implement TELNET "line mode", 155allowing them to detect 156.Xr tty 4 157state changes by the slave, and negotiate the appropriate TELNET 158protocol equivalents with the remote peer. 159.El 160.It Dv TIOCUCNTL 161Enable/disable a mode that allows a small number of simple user 162.Xr ioctl 2 163commands to be passed through the pseudo terminal, 164using a protocol similar to that of 165.Dv TIOCPKT . 166The 167.Dv TIOCUCNTL 168and 169.Dv TIOCPKT 170modes are mutually exclusive. 171This mode is enabled from the master side of a pseudo terminal 172by specifying (by reference) 173a nonzero parameter and disabled by specifying (by reference) 174a zero parameter. 175Each subsequent 176.Xr read 2 177from the master side will return data written on the slave part of 178the pseudo terminal preceded by a zero byte, 179or a single byte reflecting a user control operation on the slave side. 180A user control command consists of a special 181.Xr ioctl 2 182operation with no data; the command is given as 183.Dv UIOCCMD Ns (n) , 184where 185.Ar n 186is a number in the range 1-255. 187The operation value 188.Ar n 189will be received as a single byte on the next 190.Xr read 2 191from the master side. 192The 193.Xr ioctl 2 194.Dv UIOCCMD Ns (0) 195is a no-op that may be used to probe for 196the existence of this facility. 197As with 198.Dv TIOCPKT 199mode, command operations may be detected with a 200.Xr select 2 201for exceptional conditions. 202.It Dv TIOCREMOTE 203A mode for the master half of a pseudo terminal, independent 204of 205.Dv TIOCPKT . 206This mode causes input to the pseudo terminal 207to be flow controlled and not input edited (regardless of the terminal mode). 208Each write to the control terminal produces a record boundary for the process 209reading the terminal. 210In normal usage, a write of data is like the data typed as a line 211on the terminal; a write of 0 bytes is like typing an end-of-file 212character. 213.Dv TIOCREMOTE 214can be used when doing remote line 215editing in a window manager, or whenever flow controlled input 216is required. 217.El 218.Pp 219The standard way to allocate 220.Nm 221devices is through 222.Xr openpty 3 , 223a function which internally uses a 224.Dv PTMGET 225.Xr ioctl 2 226call on the 227.Pa /dev/ptm 228device. 229The 230.Dv PTMGET 231command allocates a free pseudo terminal, changes its ownership to 232the caller, revokes the access privileges for all previous users, 233opens the file descriptors for the master and slave devices and returns 234them to the caller in 235.Fa struct ptmget . 236.Bd -literal -offset indent 237struct ptmget { 238 int cfd; 239 int sfd; 240 char cn[16]; 241 char sn[16]; 242}; 243.Ed 244.Pp 245The 246.Va cfd 247and 248.Va sfd 249fields are the file descriptors for the controlling and slave terminals. 250The 251.Va cn 252and 253.Va sn 254fields are the file names of the controlling and slave devices. 255.Sh FILES 256.Bl -tag -width /dev/tty[p-zP-T][0-9a-zA-Z]x -compact 257.It Pa /dev/pty[p-zP-T][0-9a-zA-Z] 258master pseudo terminals 259.It Pa /dev/tty[p-zP-T][0-9a-zA-Z] 260slave pseudo terminals 261.It Pa /dev/ptm 262pseudo terminal management device 263.El 264.Sh SEE ALSO 265.Xr openpty 3 , 266.Xr tty 4 , 267.Xr sysctl 8 268.Sh HISTORY 269The 270.Nm 271driver appeared in 272.Bx 4.2 . 273The 274.Pa /dev/ptm 275device was added in 276.Ox 3.5 . 277.Sh CAVEATS 278The 279.Pa ptm 280device will only work on systems where the 281.Pa /dev 282directory has been properly populated with 283.Nm 284device nodes following the naming convention used in 285.Ox . 286Since 287.Pa ptm 288impersonates the super user for some operations it needs to perform 289to complete the allocation of a pseudo terminal, the 290.Pa /dev 291directory must also be writeable by the super user. 292