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