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