share/man/man7d/pty.7d

   1 '\" te
   2 .\" Copyright (c) 1994, Sun Microsystems, Inc.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH PTY 7D "Aug 8, 1994"
   7 .SH NAME
   8 pty \- pseudo-terminal driver
   9 .SH DESCRIPTION
  10 .sp
  11 .LP
  12 The \fBpty\fR driver provides support for a pair of devices collectively known
  13 as a \fIpseudo-terminal\fR. The two devices comprising a pseudo-terminal are
  14 known as a \fIcontroller\fR and a \fIslave\fR. The slave device distinguishes
  15 between the \fBB0\fR baud rate and other baud rates specified in the
  16 \fBc_cflag\fR word of the \fBtermios\fR structure, and the \fBCLOCAL\fR flag in
  17 that word. It does not support any of the other \fBtermio\fR(7I) device control
  18 functions specified by flags in the \fBc_cflag\fR word of the \fBtermios\fR
  19 structure and by the \fB\fR\fBIGNBRK\fR\fB, \fR \fB\fR\fBIGNPAR\fR\fB, \fR
  20 \fB\fR\fBPARMRK\fR\fB, \fR or \fBINPCK\fR flags in the \fBc_iflag\fR word of
  21 the \fBtermios\fR structure, as these functions apply only to asynchronous
  22 serial ports.  All other \fBtermio\fR(7I) functions must be performed by
  23 \fBSTREAMS\fR modules pushed atop the driver; when a slave device is opened,
  24 the \fBldterm\fR(7M) and \fBttcompat\fR(7M) \fBSTREAMS\fR modules are
  25 automatically pushed on top of the stream, providing the standard
  26 \fBtermio\fR(7I) interface.
  27 .sp
  28 .LP
  29 Instead of having a hardware interface and associated hardware that supports
  30 the terminal functions, the functions are implemented by another process
  31 manipulating the controller device of the pseudo-terminal.
  32 .sp
  33 .LP
  34 The controller and the slave devices of the pseudo-terminal are tightly
  35 connected. Any data written on the controller device is given to the slave
  36 device as input, as though it had been received from a hardware interface. Any
  37 data written on the slave terminal can be read from the controller device
  38 (rather than being transmitted from a \fBUAR\fR).
  39 .sp
  40 .LP
  41 By default, 48 pseudo-terminal pairs are configured as follows:
  42 .sp
  43 .in +2
  44 .nf
  45 /dev/pty[p-r][0-9a-f] controller devices
  46 /dev/tty[p-r][0-9a-f] slave devices
  47 .fi
  48 .in -2
  49
  50 .SH IOCTLS
  51 .sp
  52 .LP
  53 The standard set of \fBtermio ioctl\fRs are supported by the slave device.
  54 None of the bits in the \fBc_cflag\fR word have any effect on the
  55 pseudo-terminal, except that if the baud rate is set to \fBB0\fR, it will
  56 appear to the process on the controller device as if the last process on the
  57 slave device had closed the line; thus, setting the baud rate to \fBB0\fR has
  58 the effect of ``hanging up'' the pseudo-terminal, just as it has the effect of
  59 ``hanging up'' a real terminal.
  60 .sp
  61 .LP
  62 There is no notion of ``parity'' on a pseudo-terminal, so none of the flags in
  63 the \fBc_iflag\fR word that control the processing of parity errors have any
  64 effect. Similarly, there is no notion of a ``break'', so none of the flags that
  65 control the processing of breaks, and none of the \fBioctl\fRs that generate
  66 breaks, have any effect.
  67 .sp
  68 .LP
  69 Input flow control is automatically performed; a process that attempts to write
  70 to the controller device will be blocked if too much unconsumed data is
  71 buffered on the slave device.  The input flow control provided by the
  72 \fBIXOFF\fR flag in the \fBc_iflag\fR word is not supported.
  73 .sp
  74 .LP
  75 The delays specified in the \fBc_oflag\fR word are not supported.
  76 .sp
  77 .LP
  78 As there are no modems involved in a pseudo-terminal, the \fBioctl\fRs that
  79 return or alter the state of modem control lines are silently ignored.
  80 .sp
  81 .LP
  82 A few special \fBioctl\fRs are provided on the controller devices of
  83 pseudo-terminals to provide the functionality needed by applications programs
  84 to emulate real hardware interfaces:
  85 .sp
  86 .ne 2
  87 .na
  88 \fB\fBTIOCSTOP\fR\fR
  89 .ad
  90 .RS 14n
  91 The argument is ignored. Output to the pseudo-terminal is suspended, as if a
  92 \fBSTOP\fR character had been typed.
  93 .RE
  94
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fBTIOCSTART\fR\fR
  99 .ad
 100 .RS 14n
 101 The argument is ignored. Output to the pseudo-terminal is restarted, as if a
 102 \fBSTART\fR character had been typed.
 103 .RE
 104
 105 .sp
 106 .ne 2
 107 .na
 108 \fB\fBTIOCPKT\fR\fR
 109 .ad
 110 .RS 14n
 111 The argument is a pointer to an \fBint\fR. If the value of the \fBint\fR is
 112 non-zero, \fIpacket\fR mode is enabled; if the value of the \fBint\fR is zero,
 113 packet mode is disabled. When a pseudo-terminal is in packet mode, each
 114 subsequent \fBread\fR(2) from the controller device will return data written on
 115 the slave device preceded by a zero byte (symbolically defined as
 116 \fB\fR\fBTIOCPKT_DATA\fR\fB), \fR or a single byte reflecting control status
 117 information.  In the latter case, the byte is an inclusive-or of zero or more
 118 of the bits:
 119 .sp
 120 .ne 2
 121 .na
 122 \fB\fBTIOCPKT_FLUSHREAD\fR\fR
 123 .ad
 124 .RS 22n
 125 whenever the read queue for the terminal is flushed.
 126 .RE
 127
 128 .sp
 129 .ne 2
 130 .na
 131 \fB\fBTIOCPKT_FLUSHWRITE\fR\fR
 132 .ad
 133 .RS 22n
 134 whenever the write queue for the terminal is flushed.
 135 .RE
 136
 137 .sp
 138 .ne 2
 139 .na
 140 \fB\fBTIOCPKT_STOP\fR\fR
 141 .ad
 142 .RS 22n
 143 whenever output to the terminal is stopped using ^S.
 144 .RE
 145
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fBTIOCPKT_START\fR\fR
 150 .ad
 151 .RS 22n
 152 whenever output to the terminal is restarted.
 153 .RE
 154
 155 .sp
 156 .ne 2
 157 .na
 158 \fB\fBTIOCPKT_DOSTOP\fR\fR
 159 .ad
 160 .RS 22n
 161 whenever \fBXON/XOFF\fR flow control is enabled after being disabled; it is
 162 considered ``enabled'' when the \fBIXON\fR flag in the \fBc_iflag\fR word is
 163 set, the \fBVSTOP\fR member of the \fBc_cc\fR array is ^S and the \fBVSTART\fR
 164 member of the \fBc_cc\fR array is ^Q.
 165 .RE
 166
 167 .sp
 168 .ne 2
 169 .na
 170 \fB\fBTIOCPKT_NOSTOP\fR\fR
 171 .ad
 172 .RS 22n
 173 whenever \fBXON/XOFF\fR flow control is disabled after being enabled.
 174 .RE
 175
 176 .RE
 177
 178 .sp
 179 .ne 2
 180 .na
 181 \fB\fBTIOCREMOTE\fR\fR
 182 .ad
 183 .RS 14n
 184 The argument is a pointer to an \fBint\fR. If the value of the \fBint\fR is
 185 non-zero, \fIremote\fR mode is enabled; if the value of the \fBint\fR is zero,
 186 remote mode is disabled. This mode can be enabled or disabled independently of
 187 packet mode. When a pseudo-terminal is in remote mode, input to the slave
 188 device of the pseudo-terminal is flow controlled and not input edited
 189 (regardless of the mode the slave side of the pseudo-terminal). Each write to
 190 the controller device produces a record boundary for the process reading the
 191 slave device.  In normal usage, a write of data is like the data typed as a
 192 line on the terminal; a write of 0 bytes is like typing an \fBEOF\fR character.
 193 Note: this means that a process writing to a pseudo-terminal controller in
 194 \fIremote\fR mode must keep track of line boundaries, and write only one line
 195 at a time to the controller.  If, for example, it were to buffer up several
 196 \fBNEWLINE\fR characters and write them to the controller with one
 197 \fBwrite()\fR, it would appear to a process reading from the slave as if a
 198 single line containing several \fBNEWLINE\fR characters had been typed (as if,
 199 for example, a user had typed the \fBLNEXT\fR character before typing all but
 200 the last of those \fBNEWLINE\fR characters). Remote mode can be used when doing
 201 remote line editing in a window manager, or whenever flow controlled input is
 202 required.
 203 .RE
 204
 205 .SH EXAMPLES
 206 .sp
 207 .in +2
 208 .nf
 209 #include <fcntl.h>
 210 #include <sys/termios.h>
 211
 212 int fdm fds;
 213 fdm = open("/dev/ptyp0, O_RDWR);  /* open master */
 214 fds = open("/dev/ttyp0, O_RDWR);  /* open slave */
 215 .fi
 216 .in -2
 217
 218 .SH FILES
 219 .sp
 220 .ne 2
 221 .na
 222 \fB\fB/dev/pty[p-z][0-9a-f]\fR\fR
 223 .ad
 224 .RS 25n
 225 pseudo-terminal controller devices
 226 .RE
 227
 228 .sp
 229 .ne 2
 230 .na
 231 \fB\fB/dev/tty[p-z][0-9a-f]\fR\fR
 232 .ad
 233 .RS 25n
 234 pseudo-terminal slave devices
 235 .RE
 236
 237 .SH SEE ALSO
 238 .sp
 239 .LP
 240 \fBrlogin\fR(1), \fBrlogind\fR(8), \fBldterm\fR(7M), \fBtermio\fR(7I),
 241 \fBttcompat\fR(7M),
 242 .SH NOTES
 243 .sp
 244 .LP
 245 It is apparently not possible to send an \fBEOT\fR by writing zero bytes in
 246 \fBTIOCREMOTE\fR mode.