share/man/man4/pts.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$
  30 .\"
  31 .Dd August 20, 2008
  32 .Dt PTS 4
  33 .Os
  34 .Sh NAME
  35 .Nm pts
  36 .Nd pseudo-terminal driver
  37 .Sh DESCRIPTION
  38 The
  39 .Nm
  40 driver provides support for a device-pair termed a
  41 .Em pseudo-terminal .
  42 A pseudo-terminal is a pair of character devices, a
  43 .Em master
  44 device and a
  45 .Em slave
  46 device.
  47 The slave device provides to a process an interface identical
  48 to that described in
  49 .Xr tty 4 .
  50 However, whereas all other devices which provide the
  51 interface described in
  52 .Xr tty 4
  53 have a hardware device of some sort behind them, the slave
  54 device has, instead, another process manipulating
  55 it through the master half of the pseudo-terminal.
  56 That is, anything written on the master device is
  57 given to the slave device as input and anything written
  58 on the slave device is presented as input on the master
  59 device.
  60 .Pp
  61 The following
  62 .Xr ioctl 2
  63 calls apply only to pseudo-terminals:
  64 .Bl -tag -width TIOCPTMASTER
  65 .It Dv TIOCPKT
  66 Enable/disable
  67 .Em packet
  68 mode.
  69 Packet mode is enabled by specifying (by reference)
  70 a nonzero parameter and disabled by specifying (by reference)
  71 a zero parameter.
  72 When applied to the master side of a pseudo-terminal, each subsequent
  73 .Xr read 2
  74 from the terminal will return data written on the slave part of
  75 the pseudo-terminal preceded by a zero byte (symbolically
  76 defined as
  77 .Dv TIOCPKT_DATA ) ,
  78 or a single byte reflecting control
  79 status information.
  80 In the latter case, the byte is an inclusive-or
  81 of zero or more of the bits:
  82 .Bl -tag -width TIOCPKT_FLUSHWRITE
  83 .It Dv TIOCPKT_FLUSHREAD
  84 whenever the read queue for the terminal is flushed.
  85 .It Dv TIOCPKT_FLUSHWRITE
  86 whenever the write queue for the terminal is flushed.
  87 .It Dv TIOCPKT_STOP
  88 whenever output to the terminal is stopped a la
  89 .Ql ^S .
  90 .It Dv TIOCPKT_START
  91 whenever output to the terminal is restarted.
  92 .It Dv TIOCPKT_DOSTOP
  93 whenever
  94 .Dv VSTOP
  95 is
  96 .Ql ^S
  97 and
  98 .Dv VSTART
  99 is
 100 .Ql ^Q .
 101 .It Dv TIOCPKT_NOSTOP
 102 whenever the start and stop characters are not
 103 .Ql ^S/^Q .
 104 .El
 105 .Pp
 106 While this mode is in use, the presence of control status information
 107 to be read from the master side may be detected by a
 108 .Xr select 2
 109 for exceptional conditions.
 110 .Pp
 111 This mode is used by
 112 .Xr rlogin 1
 113 and
 114 .Xr rlogind 8
 115 to implement a remote-echoed, locally
 116 .Ql ^S/^Q
 117 flow-controlled
 118 remote login with proper back-flushing of output; it can be
 119 used by other similar programs.
 120 .It Dv TIOCGPTN
 121 Obtain device unit number, which can be used to generate the filename of
 122 the pseudo-terminal slave device.
 123 This
 124 .Xr ioctl 2
 125 should not be used directly.
 126 Instead, the
 127 .Xr ptsname 3
 128 function should be used.
 129 .It Dv TIOCPTMASTER
 130 Determine whether the file descriptor is pointing to a pseudo-terminal
 131 master device.
 132 This
 133 .Xr ioctl 2
 134 should not be used directly.
 135 It is used to implement routines like
 136 .Xr grantpt 3 .
 137 .El
 138 .Sh FILES
 139 The files used by this
 140 pseudo-terminals implementation are:
 141 .Bl -tag -width ".Pa /dev/pts/[num]"
 142 .It Pa /dev/pts/[num]
 143 Pseudo-terminal slave devices.
 144 .El
 145 .Sh DIAGNOSTICS
 146 None.
 147 .Sh SEE ALSO
 148 .Xr posix_openpt 2 ,
 149 .Xr grantpt 3 ,
 150 .Xr ptsname 3 ,
 151 .Xr pty 4 ,
 152 .Xr tty 4
 153 .Sh HISTORY
 154 A
 155 pseudo-terminal driver appeared in
 156 .Bx 4.2 .
 157 In
 158 .Fx 8.0 ,
 159 it was replaced with the
 160 .Nm
 161 driver.