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