share/man/man4/pty.4

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)pty.4       8.2 (Berkeley) 11/30/93
  29 .\" $FreeBSD: src/share/man/man4/pty.4,v 1.8.2.3 2001/08/17 13:08:39 ru Exp $
  30 .\"
  31 .Dd December 31, 2017
  32 .Dt PTY 4
  33 .Os
  34 .Sh NAME
  35 .Nm pty
  36 .Nd pseudo terminal driver
  37 .Sh SYNOPSIS
  38 .Cd "pseudo-device pty"
  39 .Sh DESCRIPTION
  40 The
  41 .Nm
  42 driver provides support for a device-pair termed a
  43 .Em pseudo terminal .
  44 A pseudo terminal is a pair of character devices, a
  45 .Em master
  46 device and a
  47 .Em slave
  48 device.  The slave device provides to a process
  49 an interface identical
  50 to that described in
  51 .Xr tty 4 .
  52 However, whereas all other devices which provide the
  53 interface described in
  54 .Xr tty 4
  55 have a hardware device of some sort behind them, the slave
  56 device has, instead, another process manipulating
  57 it through the master half of the pseudo terminal.
  58 That is, anything written on the master device is
  59 given to the slave device as input and anything written
  60 on the slave device is presented as input on the master
  61 device.
  62 .Pp
  63 The following
  64 .Xr ioctl 2
  65 calls apply only to pseudo terminals:
  66 .Bl -tag -width ".Dv TIOCREMOTE"
  67 .It Dv TIOCSTOP
  68 Stops output to a terminal (e.g. like typing
  69 .Ql ^S ) .
  70 Takes
  71 no parameter.
  72 .It Dv TIOCSTART
  73 Restarts output (stopped by
  74 .Dv TIOCSTOP
  75 or by typing
  76 .Ql ^S ) .
  77 Takes no parameter.
  78 .It Dv TIOCPKT
  79 Enable/disable
  80 .Em packet
  81 mode.  Packet mode is enabled by specifying (by reference)
  82 a nonzero parameter and disabled by specifying (by reference)
  83 a zero parameter.  When applied to the master side of a pseudo
  84 terminal, each subsequent
  85 .Xr read 2
  86 from the terminal will return data written on the slave part of
  87 the pseudo terminal preceded by a zero byte (symbolically
  88 defined as
  89 .Dv TIOCPKT_DATA ) ,
  90 or a single byte reflecting control
  91 status information.  In the latter case, the byte is an inclusive-or
  92 of zero or more of the bits:
  93 .Bl -tag -width TIOCPKT_FLUSHWRITE
  94 .It Dv TIOCPKT_FLUSHREAD
  95 whenever the read queue for the terminal is flushed.
  96 .It Dv TIOCPKT_FLUSHWRITE
  97 whenever the write queue for the terminal is flushed.
  98 .It Dv TIOCPKT_STOP
  99 whenever output to the terminal is stopped a la
 100 .Ql ^S .
 101 .It Dv TIOCPKT_START
 102 whenever output to the terminal is restarted.
 103 .It Dv TIOCPKT_DOSTOP
 104 whenever
 105 .Em t_stopc
 106 is
 107 .Ql ^S
 108 and
 109 .Em t_startc
 110 is
 111 .Ql ^Q .
 112 .It Dv TIOCPKT_NOSTOP
 113 whenever the start and stop characters are not
 114 .Ql ^S/^Q .
 115 .Pp
 116 While this mode is in use, the presence of control status information
 117 to be read from the master side may be detected by a
 118 .Xr select 2
 119 for exceptional conditions.
 120 .Pp
 121 This mode is used by
 122 .Xr rlogin 1 Pq Pa net/bsdrcmds
 123 and
 124 .Xr rlogind 8 Pq Pa net/bsdrcmds
 125 to implement a remote-echoed, locally
 126 .Ql ^S/^Q
 127 flow-controlled
 128 remote login with proper back-flushing of output; it can be
 129 used by other similar programs.
 130 .El
 131 .It Dv TIOCUCNTL
 132 Enable/disable a mode that allows a small number of simple user
 133 .Xr ioctl 2
 134 commands to be passed through the pseudo-terminal,
 135 using a protocol similar to that of
 136 .Dv TIOCPKT .
 137 The
 138 .Dv TIOCUCNTL
 139 and
 140 .Dv TIOCPKT
 141 modes are mutually exclusive.
 142 This mode is enabled from the master side of a pseudo terminal
 143 by specifying (by reference)
 144 a nonzero parameter and disabled by specifying (by reference)
 145 a zero parameter.
 146 Each subsequent
 147 .Xr read 2
 148 from the master side will return data written on the slave part of
 149 the pseudo terminal preceded by a zero byte,
 150 or a single byte reflecting a user control operation on the slave side.
 151 A user control command consists of a special
 152 .Xr ioctl 2
 153 operation with no data; the command is given as
 154 .Dv UIOCCMD Ns (n) ,
 155 where
 156 .Ar n
 157 is a number in the range 1-255.
 158 The operation value
 159 .Ar n
 160 will be received as a single byte on the next
 161 .Xr read 2
 162 from the master side.
 163 The
 164 .Xr ioctl 2
 165 .Dv UIOCCMD Ns (0)
 166 is a no-op that may be used to probe for
 167 the existence of this facility.
 168 As with
 169 .Dv TIOCPKT
 170 mode, command operations may be detected with a
 171 .Xr select 2
 172 for exceptional conditions.
 173 .It Dv TIOCREMOTE
 174 A mode for the master half of a pseudo terminal, independent
 175 of
 176 .Dv TIOCPKT .
 177 This mode causes input to the pseudo terminal
 178 to be flow controlled and not input edited (regardless of the
 179 terminal mode).  Each write to the control terminal produces
 180 a record boundary for the process reading the terminal.  In
 181 normal usage, a write of data is like the data typed as a line
 182 on the terminal; a write of 0 bytes is like typing an end-of-file
 183 character.
 184 .Dv TIOCREMOTE
 185 can be used when doing remote line
 186 editing in a window manager, or whenever flow controlled input
 187 is required.
 188 .El
 189 .Sh FILES
 190 .Bl -tag -width /dev/tty[p-sP-S][0-9a-v]x -compact
 191 .It Pa /dev/pty[p-sP-S][0-9a-v]
 192 master pseudo terminals
 193 .It Pa /dev/tty[p-sP-S][0-9a-v]
 194 slave pseudo terminals
 195 .El
 196 .Sh DIAGNOSTICS
 197 None.
 198 .Sh SEE ALSO
 199 .Xr tty 4
 200 .Sh HISTORY
 201 The
 202 .Nm
 203 driver appeared in
 204 .Bx 4.2 .