Print this page
14249 pseudo-terminal nomenclature should reflect POSIX
Change-Id: Ib4a3cef899ff4c71b09cb0dc6878863c5e8357bc
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man7d/pty.7d
+++ new/usr/src/man/man7d/pty.7d
1 1 '\" te
2 2 .\" Copyright (c) 1994, Sun Microsystems, Inc.
3 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 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 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
6 +.\" Copyright 2022 Oxide Computer Company
7 +.Dd February 5, 2022
8 +.Dt PTY 7D
9 +.Os
10 +.Sh NAME
11 +.Nm pty
12 +.Nd legacy pseudo-terminal driver
13 +.Sh SYNOPSIS
14 +.Pa /dev/pty[p-r]*
15 +.Pp
16 +.Pa /dev/tty[p-r]*
17 +.Sh DESCRIPTION
18 +This driver provides support for legacy static pseudo-terminal devices.
19 +Modern software does not use this driver, preferring instead the STREAMS-based
20 +.Xr ptm 7D
21 +and
22 +.Xr pts 7D
23 +pseudo-terminal drivers, consumed through the portable
24 +.Xr posix_openpt 3C
25 +interface.
26 +.Pp
27 +The
28 +.Nm pty
29 +driver provides support for a pair of devices collectively known
30 +as a
31 +.Em pseudo-terminal .
32 +The two devices comprising a pseudo-terminal are known as a
33 +.Em manager
34 +and a
35 +.Em subsidiary .
36 +The subsidiary device distinguishes between the
37 +.Dv B0 baud rate and other baud rates specified in
38 +the
39 +.Fa c_cflag
40 +field of the
41 +.Vt termios
42 +structure, and the
43 +.Dv CLOCAL
44 +flag in that member.
45 +It does not support any of the other
46 +.Xr termio 7I
47 +device control functions specified by flags in the
48 +.Fa c_cflag
49 +field of the
50 +.Vt termios
51 +structure and by the
52 +.Dv IGNBRK ,
53 +.Dv IGNPAR ,
54 +.Dv PARMRK ,
55 +or
56 +.Dv INPCK
57 +flags in the
58 +.Fa c_iflag
59 +field of the
60 +.Vt termios
61 +structure, as these functions apply only to asynchronous serial ports.
62 +All other
63 +.Xr termio 7I
64 +functions must be performed by STREAMS modules pushed atop the driver; when a
65 +subsidiary device is opened, the
66 +.Xr ldterm 7M
67 +and
68 +.Xr ttcompat 7M
69 +STREAMS modules are automatically pushed on top of the stream, providing the
70 +standard
71 +.Xr termio 7I
72 +interface.
73 +.Pp
29 74 Instead of having a hardware interface and associated hardware that supports
30 75 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
76 +manipulating the manager device of the pseudo-terminal.
77 +.Pp
78 +The manager and the subsidiary devices of the pseudo-terminal are tightly
79 +connected.
80 +Any data written on the manager device is given to the subsidiary device as
81 +input, as though it had been received from a hardware interface.
82 +Any data written on the subsidiary terminal can be read from the manager device
83 +.Pq "rather than being transmitted from a UAR" .
84 +.Pp
85 +The driver is statically configured to provide 48 pseudo-terminal pairs.
86 +Software that requires dynamic pseudo-terminal devices, or a greater number
87 +of devices, must be converted to use
88 +.Xr ptm 7D .
89 +.Sh IOCTLS
90 +The standard set of
91 +.Xr termio 7I
92 +ioctls are supported by the subsidiary device.
93 +None of the bits in the
94 +.Fa c_cflag
95 +field have any effect on the pseudo-terminal, except that if the baud rate is
96 +set to
97 +.Dv B0 ,
98 +it will appear to the process on the manager device as if the last process on
99 +the subsidiary device had closed the line; thus, setting the baud rate to
100 +.Dv B0
101 +has the effect of
102 +.Dq hanging up
103 +the pseudo-terminal, just as it has the effect of
104 +.Dq hanging up
105 +a real terminal.
106 +.Pp
107 +There is no notion of
108 +.Dq parity
109 +on a pseudo-terminal, so none of the flags in the
110 +.Fa c_iflag
111 +field that control the processing of parity errors have any
112 +effect.
113 +Similarly, there is no notion of a
114 +.Fa break ,
115 +so none of the flags that control the processing of breaks, and none of the
116 +ioctls that generate breaks, have any effect.
117 +.Pp
69 118 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(1M), \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.
119 +to the manager device will be blocked if too much unconsumed data is buffered
120 +on the subsidiary device.
121 +The input flow control provided by the
122 +.Dv IXOFF
123 +flag in the
124 +.Fa c_iflag
125 +field is not supported.
126 +.Pp
127 +The delays specified in the
128 +.Fa c_oflag
129 +field are not supported.
130 +.Pp
131 +As there are no modems involved in a pseudo-terminal, the ioctls that return or
132 +alter the state of modem control lines are silently ignored.
133 +.Pp
134 +A few special ioctls are provided on the manager devices of pseudo-terminals to
135 +provide the functionality needed by applications programs to emulate real
136 +hardware interfaces:
137 +.Bl -tag -width Ds
138 +.It Dv TIOCSTOP
139 +The argument is ignored.
140 +Output to the pseudo-terminal is suspended, as if a
141 +.Sy STOP
142 +character had been typed.
143 +.It Dv TIOCSTART
144 +The argument is ignored.
145 +Output to the pseudo-terminal is restarted, as if a
146 +.Sy START
147 +character had been typed.
148 +.It Dv TIOCPKT
149 +The argument is a pointer to an
150 +.Vt int .
151 +If the value of the
152 +.Vt int
153 +is non-zero,
154 +.Em packet
155 +mode is enabled; if the value of the
156 +.Vt int
157 +is zero, packet mode is disabled.
158 +When a pseudo-terminal is in packet mode, each subsequent
159 +.Xr read 2
160 +from the manager device will return data written on the subsidiary device
161 +preceded by a zero byte
162 +.Po
163 +symbolically defined as
164 +.Dv TIOCPKT_DATA
165 +.Pc ,
166 +or a single byte reflecting control status information.
167 +In the latter case, the byte is an inclusive-or of zero or more of the bits:
168 +.Bl -tag -width Ds
169 +.It Dv TIOCPKT_FLUSHREAD
170 +Whenever the read queue for the terminal is flushed.
171 +.It Dv TIOCPKT_FLUSHWRITE
172 +Whenever the write queue for the terminal is flushed.
173 +.It Dv TIOCPKT_STOP
174 +Whenever output to the terminal is stopped using
175 +.Sy ^S .
176 +.It Dv TIOCPKT_START
177 +Whenever output to the terminal is restarted.
178 +.It Dv TIOCPKT_DOSTOP
179 +Whenever
180 +.Em XON/XOFF
181 +flow control is enabled after being disabled; it is
182 +considered
183 +.Dq enabled
184 +when the
185 +.Dv IXON
186 +flag in the
187 +.Fa c_iflag
188 +field is set, the
189 +.Dv VSTOP
190 +member of the
191 +.Fa c_cc
192 +array is
193 +.Sy ^S
194 +and the
195 +.Dv VSTART
196 +member of the
197 +.Fa c_cc
198 +array is
199 +.Sy ^Q.
200 +.It Dv TIOCPKT_NOSTOP
201 +Whenever
202 +.Em XON/XOFF
203 +flow control is disabled after being enabled.
204 +.El
205 +.It Dv TIOCREMOTE
206 +The argument is a pointer to an
207 +.Vt int .
208 +If the value of the
209 +.Vt int
210 +is non-zero,
211 +.Em remote
212 +mode is enabled; if the value of the
213 +.Vt int
214 +is zero, remote mode is disabled.
215 +This mode can be enabled or disabled independently of packet mode.
216 +When a pseudo-terminal is in remote mode, input to the subsidiary device of the
217 +pseudo-terminal is flow controlled and not input edited (regardless of the mode
218 +the subsidiary side of the pseudo-terminal).
219 +.Pp
220 +Each write to the manager device produces a record boundary for the process
221 +reading the subsidiary device.
222 +In normal usage, a write of data is like the data typed as a line on the
223 +terminal; a write of 0 bytes is like typing an
224 +.Sy EOF
225 +character.
226 +Note: this means that a process writing to a pseudo-terminal manager in remote
227 +mode must keep track of line boundaries, and write only one line at a time to
228 +the manager.
229 +.Pp
230 +If, for example, it were to buffer up several newline characters and write them
231 +to the manager with one
232 +.Xr write 2 ,
233 +it would appear to a process reading from the subsidiary as if a single line
234 +containing several newline characters had been typed
235 +.Po
236 +as if, for example, a user had typed the literal next
237 +.Pq Sy LNEXT
238 +character before typing all but the last of those newline characters
239 +.Pc .
240 +Remote mode can be used when doing remote line editing in a window manager, or
241 +whenever flow controlled input is required.
242 +.El
243 +.Sh FILES
244 +.Bl -tag -width Pa
245 +.It Pa /dev/pty[p-r][0-9a-f]
246 +Pseudo-terminal manager devices.
247 +.It Pa /dev/tty[p-r][0-9a-f]
248 +Pseudo-terminal subsidiary devices.
249 +.El
250 +.Sh SEE ALSO
251 +.Xr rlogin 1 ,
252 +.Xr rlogind 1M ,
253 +.Xr posix_openpty 3C ,
254 +.Xr ptm 7D ,
255 +.Xr termio 7I ,
256 +.Xr ldterm 7M ,
257 +.Xr ttcompat 7M
258 +.Sh NOTES
259 +This is a legacy device and should not be used by new software.
260 +.Pp
261 +It is apparently not possible to send an
262 +.Sy EOT
263 +by writing zero bytes in
264 +.Dv TIOCREMOTE
265 +mode.
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX