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