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