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. 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 .\" $FreeBSD: src/share/man/man4/pty.4,v 1.8.2.3 2001/08/17 13:08:39 ru Exp $
  34 .\"
  35 .Dd November 30, 1993
  36 .Dt PTY 4
  37 .Os
  38 .Sh NAME
  39 .Nm pty
  40 .Nd pseudo terminal driver
  41 .Sh SYNOPSIS
  42 .Cd "pseudo-device pty"
  43 .Sh DESCRIPTION
  44 The
  45 .Nm
  46 driver provides support for a device-pair termed a
  47 .Em pseudo terminal .
  48 A pseudo terminal is a pair of character devices, a
  49 .Em master
  50 device and a
  51 .Em slave
  52 device.  The slave device provides to a process
  53 an interface identical
  54 to that described in
  55 .Xr tty 4 .
  56 However, whereas all other devices which provide the
  57 interface described in
  58 .Xr tty 4
  59 have a hardware device of some sort behind them, the slave
  60 device has, instead, another process manipulating
  61 it through the master half of the pseudo terminal.
  62 That is, anything written on the master device is
  63 given to the slave device as input and anything written
  64 on the slave device is presented as input on the master
  65 device.
  66 .Pp
  67 The following
  68 .Xr ioctl 2
  69 calls apply only to pseudo terminals:
  70 .Bl -tag -width TIOCREMOTE
  71 .It Dv TIOCSTOP
  72 Stops output to a terminal (e.g. like typing
  73 .Ql ^S ) .
  74 Takes
  75 no parameter.
  76 .It Dv TIOCSTART
  77 Restarts output (stopped by
  78 .Dv TIOCSTOP
  79 or by typing
  80 .Ql ^S ) .
  81 Takes no parameter.
  82 .It Dv TIOCPKT
  83 Enable/disable
  84 .Em packet
  85 mode.  Packet mode is enabled by specifying (by reference)
  86 a nonzero parameter and disabled by specifying (by reference)
  87 a zero parameter.  When applied to the master side of a pseudo
  88 terminal, each subsequent
  89 .Xr read 2
  90 from the terminal will return data written on the slave part of
  91 the pseudo terminal preceded by a zero byte (symbolically
  92 defined as
  93 .Dv TIOCPKT_DATA ) ,
  94 or a single byte reflecting control
  95 status information.  In the latter case, the byte is an inclusive-or
  96 of zero or more of the bits:
  97 .Bl -tag -width TIOCPKT_FLUSHWRITE
  98 .It Dv TIOCPKT_FLUSHREAD
  99 whenever the read queue for the terminal is flushed.
 100 .It Dv TIOCPKT_FLUSHWRITE
 101 whenever the write queue for the terminal is flushed.
 102 .It Dv TIOCPKT_STOP
 103 whenever output to the terminal is stopped a la
 104 .Ql ^S .
 105 .It Dv TIOCPKT_START
 106 whenever output to the terminal is restarted.
 107 .It Dv TIOCPKT_DOSTOP
 108 whenever
 109 .Em t_stopc
 110 is
 111 .Ql ^S
 112 and
 113 .Em t_startc
 114 is
 115 .Ql ^Q .
 116 .It Dv TIOCPKT_NOSTOP
 117 whenever the start and stop characters are not
 118 .Ql ^S/^Q .
 119 .Pp
 120 While this mode is in use, the presence of control status information
 121 to be read from the master side may be detected by a
 122 .Xr select 2
 123 for exceptional conditions.
 124 .Pp
 125 This mode is used by
 126 .Xr rlogin 1
 127 and
 128 .Xr rlogind 8
 129 to implement a remote-echoed, locally
 130 .Ql ^S/^Q
 131 flow-controlled
 132 remote login with proper back-flushing of output; it can be
 133 used by other similar programs.
 134 .El
 135 .It Dv TIOCUCNTL
 136 Enable/disable a mode that allows a small number of simple user
 137 .Xr ioctl 2
 138 commands to be passed through the pseudo-terminal,
 139 using a protocol similar to that of
 140 .Dv TIOCPKT .
 141 The
 142 .Dv TIOCUCNTL
 143 and
 144 .Dv TIOCPKT
 145 modes are mutually exclusive.
 146 This mode is enabled from the master side of a pseudo terminal
 147 by specifying (by reference)
 148 a nonzero parameter and disabled by specifying (by reference)
 149 a zero parameter.
 150 Each subsequent
 151 .Xr read 2
 152 from the master side will return data written on the slave part of
 153 the pseudo terminal preceded by a zero byte,
 154 or a single byte reflecting a user control operation on the slave side.
 155 A user control command consists of a special
 156 .Xr ioctl 2
 157 operation with no data; the command is given as
 158 .Dv UIOCCMD Ns (n) ,
 159 where
 160 .Ar n
 161 is a number in the range 1-255.
 162 The operation value
 163 .Ar n
 164 will be received as a single byte on the next
 165 .Xr read 2
 166 from the master side.
 167 The
 168 .Xr ioctl 2
 169 .Dv UIOCCMD Ns (0)
 170 is a no-op that may be used to probe for
 171 the existence of this facility.
 172 As with
 173 .Dv TIOCPKT
 174 mode, command operations may be detected with a
 175 .Xr select 2
 176 for exceptional conditions.
 177 .It Dv TIOCREMOTE
 178 A mode for the master half of a pseudo terminal, independent
 179 of
 180 .Dv TIOCPKT .
 181 This mode causes input to the pseudo terminal
 182 to be flow controlled and not input edited (regardless of the
 183 terminal mode).  Each write to the control terminal produces
 184 a record boundary for the process reading the terminal.  In
 185 normal usage, a write of data is like the data typed as a line
 186 on the terminal; a write of 0 bytes is like typing an end-of-file
 187 character.
 188 .Dv TIOCREMOTE
 189 can be used when doing remote line
 190 editing in a window manager, or whenever flow controlled input
 191 is required.
 192 .El
 193 .Sh FILES
 194 .Bl -tag -width /dev/tty[p-sP-S][0-9a-v]x -compact
 195 .It Pa /dev/pty[p-sP-S][0-9a-v]
 196 master pseudo terminals
 197 .It Pa /dev/tty[p-sP-S][0-9a-v]
 198 slave pseudo terminals
 199 .El
 200 .Sh DIAGNOSTICS
 201 None.
 202 .Sh SEE ALSO
 203 .Xr tty 4
 204 .Sh HISTORY
 205 The
 206 .Nm
 207 driver appeared in
 208 .Bx 4.2 .