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. 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$
  34 .\"
  35 .Dd August 20, 2008
  36 .Dt PTS 4
  37 .Os
  38 .Sh NAME
  39 .Nm pts
  40 .Nd pseudo-terminal driver
  41 .Sh DESCRIPTION
  42 The
  43 .Nm
  44 driver provides support for a device-pair termed a
  45 .Em pseudo-terminal .
  46 A pseudo-terminal is a pair of character devices, a
  47 .Em master
  48 device and a
  49 .Em slave
  50 device.
  51 The slave device provides to a process an interface identical
  52 to that described in
  53 .Xr tty 4 .
  54 However, whereas all other devices which provide the
  55 interface described in
  56 .Xr tty 4
  57 have a hardware device of some sort behind them, the slave
  58 device has, instead, another process manipulating
  59 it through the master half of the pseudo-terminal.
  60 That is, anything written on the master device is
  61 given to the slave device as input and anything written
  62 on the slave device is presented as input on the master
  63 device.
  64 .Pp
  65 The following
  66 .Xr ioctl 2
  67 calls apply only to pseudo-terminals:
  68 .Bl -tag -width TIOCPTMASTER
  69 .It Dv TIOCPKT
  70 Enable/disable
  71 .Em packet
  72 mode.
  73 Packet mode is enabled by specifying (by reference)
  74 a nonzero parameter and disabled by specifying (by reference)
  75 a zero parameter.
  76 When applied to the master side of a pseudo-terminal, each subsequent
  77 .Xr read 2
  78 from the terminal will return data written on the slave part of
  79 the pseudo-terminal preceded by a zero byte (symbolically
  80 defined as
  81 .Dv TIOCPKT_DATA ) ,
  82 or a single byte reflecting control
  83 status information.
  84 In the latter case, the byte is an inclusive-or
  85 of zero or more of the bits:
  86 .Bl -tag -width TIOCPKT_FLUSHWRITE
  87 .It Dv TIOCPKT_FLUSHREAD
  88 whenever the read queue for the terminal is flushed.
  89 .It Dv TIOCPKT_FLUSHWRITE
  90 whenever the write queue for the terminal is flushed.
  91 .It Dv TIOCPKT_STOP
  92 whenever output to the terminal is stopped a la
  93 .Ql ^S .
  94 .It Dv TIOCPKT_START
  95 whenever output to the terminal is restarted.
  96 .It Dv TIOCPKT_DOSTOP
  97 whenever
  98 .Dv VSTOP
  99 is
 100 .Ql ^S
 101 and
 102 .Dv VSTART
 103 is
 104 .Ql ^Q .
 105 .It Dv TIOCPKT_NOSTOP
 106 whenever the start and stop characters are not
 107 .Ql ^S/^Q .
 108 .El
 109 .Pp
 110 While this mode is in use, the presence of control status information
 111 to be read from the master side may be detected by a
 112 .Xr select 2
 113 for exceptional conditions.
 114 .Pp
 115 This mode is used by
 116 .Xr rlogin 1
 117 and
 118 .Xr rlogind 8
 119 to implement a remote-echoed, locally
 120 .Ql ^S/^Q
 121 flow-controlled
 122 remote login with proper back-flushing of output; it can be
 123 used by other similar programs.
 124 .It Dv TIOCGPTN
 125 Obtain device unit number, which can be used to generate the filename of
 126 the pseudo-terminal slave device. This
 127 .Xr ioctl 2
 128 should not be used directly. Instead, the
 129 .Xr ptsname 3
 130 function should be used.
 131 .It Dv TIOCPTMASTER
 132 Determine whether the file descriptor is pointing to a pseudo-terminal
 133 master device.
 134 This
 135 .Xr ioctl 2
 136 should not be used directly. It is used to implement routines like
 137 .Xr grantpt 3 .
 138 .El
 139 .Pp
 140 The maximum number of pseudo-terminals is limited to 1000.
 141 It is not possible to use more than 1000 pseudo-terminals, as all software
 142 which use
 143 .Xr utmp 5
 144 will not be able to handle pseudo-terminals with number superior to 999.
 145 .Sh FILES
 146 The files used by this
 147 pseudo-terminals implementation are:
 148 .Pp
 149 .Bl -tag -width ".Pa /dev/pts/[num]"
 150 .It Pa /dev/ptmx
 151 Control device, returns a file descriptor to a new master
 152 pseudo-terminal when opened.
 153 This device should not be opened directly.
 154 It's only available for binary compatibility.
 155 New devices should only be allocated with
 156 .Xr posix_openpt 2
 157 and
 158 .Xr openpty 3 .
 159 .It Pa /dev/pts/[num]
 160 Pseudo-terminal slave devices.
 161 .El
 162 .Sh SYSCTL VARIABLES
 163 The following
 164 .Xr sysctl 8
 165 variables can be used to modify or monitor
 166 .Nm
 167 behavior.
 168 .Bl -tag -width indent
 169 .It Va kern.pts_maxdev
 170 Highest pseudo-terminal unit number to be allocated.
 171 Because
 172 .Xr utmp 5
 173 is restricted to an 8-byte line name size,
 174 .Nm
 175 will not create any pseudo-terminals with a unit number above 999 by
 176 default.
 177 After increasing
 178 .Dv UT_LINESIZE ,
 179 this variable can be changed to allow more than 1000 pseudo-terminals to
 180 be allocated simultaneously.
 181 .El
 182 .Sh DIAGNOSTICS
 183 None.
 184 .Sh SEE ALSO
 185 .Xr grantpt 3 ,
 186 .Xr posix_openpt 2 ,
 187 .Xr ptsname 3 ,
 188 .Xr pty 4 ,
 189 .Xr tty 4
 190 .Sh HISTORY
 191 A
 192 pseudo-terminal driver appeared in
 193 .Bx 4.2 .
 194 In
 195 .Fx 8.0 ,
 196 it was replaced with the
 197 .Nm
 198 driver.