1.\" $OpenBSD: pty.4,v 1.23 2016/06/30 15:59:30 tedu 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: June 30 2016 $ 34.Dt PTY 4 35.Os 36.Sh NAME 37.Nm pty , 38.Nm ptm 39.Nd pseudo terminal driver 40.Sh SYNOPSIS 41.Cd "pseudo-device pty" Op Ar count 42.Sh DESCRIPTION 43The 44.Nm 45driver provides support for a device-pair termed a 46.Em pseudo terminal . 47A pseudo terminal is a pair of character devices, a 48.Em master 49device and a 50.Em slave 51device. 52The slave device provides to a process an interface identical to that 53described in 54.Xr tty 4 . 55However, whereas all other devices which provide the 56interface described in 57.Xr tty 4 58have a hardware device of some sort behind them, the slave 59device has, instead, another process manipulating 60it through the master half of the pseudo terminal. 61That is, anything written on the master device is 62given to the slave device as input and anything written 63on the slave device is presented as input on the master 64device. 65.Pp 66In configuring, if an optional 67.Ar count 68is given in 69the specification, space for that number of pseudo terminal pairs is 70preallocated. 71If the count is missing or is less than 2, a default count of 8 is used. 72This is not a hard limit--space for additional pseudo terminal pairs 73is allocated on demand up to the limit of 992. 74.Pp 75The following 76.Xr ioctl 2 77calls apply only to pseudo terminals and may only be applied to the 78.Nm 79master: 80.Bl -tag -width TIOCREMOTE 81.It Dv TIOCEXT 82Enable/disable 83.Em external processing . 84External processing is enabled by specifying (by reference) a non-zero 85.Vt int 86parameter 87and disabled by specifying (by reference) a zero 88.Vt int 89parameter. 90.Pp 91While external processing is enabled, input line editing, character echo, 92and mapping of control characters to signals are disabled 93regardless of the terminal's 94.Xr termios 4 95settings. 96.It Dv TIOCSTOP 97Stops output to a terminal (e.g., like typing 98.Ql ^S ) . 99Takes 100no parameter. 101.It Dv TIOCSTART 102Restarts output (stopped by 103.Dv TIOCSTOP 104or by typing 105.Ql ^S ) . 106Takes no parameter. 107.It Dv TIOCPKT 108Enable/disable 109.Em packet 110mode. 111Packet mode is enabled by specifying (by reference) a non-zero 112.Vt int 113parameter 114and disabled by specifying (by reference) a zero 115.Vt int 116parameter. 117.Pp 118While packet mode is enabled, each subsequent 119.Xr read 2 120from the 121.Nm 122master will either return data written to the 123.Nm 124slave preceded by a zero byte (symbolically defined as 125.Dv TIOCPKT_DATA ) , 126or a single byte reflecting control 127status information. 128In the latter case, the byte is an inclusive-or of zero or more of the bits: 129.Bl -tag -width TIOCPKT_FLUSHWRITE 130.It Dv TIOCPKT_FLUSHREAD 131whenever the read queue for the terminal is flushed. 132.It Dv TIOCPKT_FLUSHWRITE 133whenever the write queue for the terminal is flushed. 134.It Dv TIOCPKT_STOP 135whenever output to the terminal is stopped a la 136.Ql ^S . 137.It Dv TIOCPKT_START 138whenever output to the terminal is restarted. 139.It Dv TIOCPKT_DOSTOP 140whenever 141.Em t_stopc 142is 143.Ql ^S 144and 145.Em t_startc 146is 147.Ql ^Q . 148.It Dv TIOCPKT_NOSTOP 149whenever the start and stop characters are not 150.Ql ^S/^Q . 151.It Dv TIOCPKT_IOCTL 152whenever the terminal's 153.Xr termios 4 154settings change while external processing is enabled. 155.Pp 156Additionally, when the 157.Dv TIOCPKT_IOCTL 158bit is set, the remainder of the data read 159from the 160.Nm 161master is a copy of the new 162.Xr termios 4 163structure. 164.El 165.Pp 166While this mode is in use, the presence of control status information 167to be read from the master side may be detected by a 168.Xr select 2 169for exceptional conditions. 170.It Dv TIOCUCNTL 171Enable/disable a mode that allows a small number of simple user 172.Xr ioctl 2 173commands to be passed through the pseudo terminal, 174using a protocol similar to that of 175.Dv TIOCPKT . 176The 177.Dv TIOCUCNTL 178and 179.Dv TIOCPKT 180modes are mutually exclusive. 181This mode is enabled from the master side of a pseudo terminal 182by specifying (by reference) 183a nonzero parameter and disabled by specifying (by reference) 184a zero parameter. 185Each subsequent 186.Xr read 2 187from the master side will return data written on the slave part of 188the pseudo terminal preceded by a zero byte, 189or a single byte reflecting a user control operation on the slave side. 190A user control command consists of a special 191.Xr ioctl 2 192operation with no data; the command is given as 193.Dv UIOCCMD Ns (n) , 194where 195.Ar n 196is a number in the range 1-255. 197The operation value 198.Ar n 199will be received as a single byte on the next 200.Xr read 2 201from the master side. 202The 203.Xr ioctl 2 204.Dv UIOCCMD Ns (0) 205is a no-op that may be used to probe for 206the existence of this facility. 207As with 208.Dv TIOCPKT 209mode, command operations may be detected with a 210.Xr select 2 211for exceptional conditions. 212.It Dv TIOCREMOTE 213A mode for the master half of a pseudo terminal, independent 214of 215.Dv TIOCPKT . 216This mode causes input to the pseudo terminal 217to be flow controlled and not input edited (regardless of the terminal mode). 218Each write to the control terminal produces a record boundary for the process 219reading the terminal. 220In normal usage, a write of data is like the data typed as a line 221on the terminal; a write of 0 bytes is like typing an end-of-file 222character. 223.Dv TIOCREMOTE 224can be used when doing remote line 225editing in a window manager, or whenever flow controlled input 226is required. 227.El 228.Pp 229The standard way to allocate 230.Nm 231devices is through 232.Xr openpty 3 , 233a function which internally uses a 234.Dv PTMGET 235.Xr ioctl 2 236call on the 237.Pa /dev/ptm 238device. 239The 240.Dv PTMGET 241command allocates a free pseudo terminal, changes its ownership to 242the caller, revokes the access privileges for all previous users, 243opens the file descriptors for the master and slave devices and returns 244them to the caller in 245.Fa struct ptmget . 246.Bd -literal -offset indent 247struct ptmget { 248 int cfd; 249 int sfd; 250 char cn[16]; 251 char sn[16]; 252}; 253.Ed 254.Pp 255The 256.Va cfd 257and 258.Va sfd 259fields are the file descriptors for the controlling and slave terminals. 260The 261.Va cn 262and 263.Va sn 264fields are the file names of the controlling and slave devices. 265.Sh FILES 266.Bl -tag -width /dev/tty[p-zP-T][0-9a-zA-Z]x -compact 267.It Pa /dev/pty[p-zP-T][0-9a-zA-Z] 268master pseudo terminals 269.It Pa /dev/tty[p-zP-T][0-9a-zA-Z] 270slave pseudo terminals 271.It Pa /dev/ptm 272pseudo terminal management device 273.El 274.Sh SEE ALSO 275.Xr openpty 3 , 276.Xr tty 4 277.Sh HISTORY 278The 279.Nm 280driver appeared in 281.Bx 4.2 . 282The 283.Pa /dev/ptm 284device was added in 285.Ox 3.5 . 286.Sh CAVEATS 287The 288.Pa ptm 289device will only work on systems where the 290.Pa /dev 291directory has been properly populated with 292.Nm 293device nodes following the naming convention used in 294.Ox . 295Since 296.Pa ptm 297impersonates the super user for some operations it needs to perform 298to complete the allocation of a pseudo terminal, the 299.Pa /dev 300directory must also be writeable by the super user. 301