Print this page
14249 pseudo-terminal nomenclature should reflect POSIX
Change-Id: Ib4a3cef899ff4c71b09cb0dc6878863c5e8357bc
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man7d/ptm.7d
+++ new/usr/src/man/man7d/ptm.7d
1 1 '\" te
2 2 .\" Copyright (c) 1997, Sun Microsystems, Inc.
3 3 .\" All Rights Reserved
4 4 .\" 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.
5 5 .\" 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.
6 6 .\" 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]
7 -.TH PTM 7D "Feb 5, 1997"
8 -.SH NAME
9 -ptm \- STREAMS pseudo-tty master driver
10 -.SH DESCRIPTION
11 -.sp
12 -.LP
13 -The pseudo-tty subsystem simulates a terminal connection, where the master side
14 -represents the terminal and the slave represents the user process's special
15 -device end point. In order to use the pseudo-tty subsystem, a node for the
16 -master side driver \fB/dev/ptmx\fR and \fBN\fR number of nodes for the slave
17 -driver must be installed. See \fBpts\fR(7D). The master device is set up as a
18 -cloned device where its major device number is the major for the clone device
19 -and its minor device number is the major for the \fBptm\fR driver. There are no
20 -nodes in the file system for master devices. The master pseudo driver is opened
21 -using the \fBopen\fR(2) system call with \fB/dev/ptmx\fR as the device
22 -parameter. The clone open finds the next available minor device for the
23 -\fBptm\fR major device.
24 -.sp
25 -.LP
26 -A master device is available only if it and its corresponding slave device are
27 -not already open. When the master device is opened, the corresponding slave
28 -device is automatically locked out. Only one open is allowed on a master
29 -device. Multiple opens are allowed on the slave device. After both the master
30 -and slave have been opened, the user has two file descriptors which are the end
31 -points of a full duplex connection composed of two streams which are
32 -automatically connected at the master and slave drivers. The user may then push
33 -modules onto either side of the stream pair.
34 -.sp
35 -.LP
36 -The master and slave drivers pass all messages to their adjacent queues. Only
37 -the \fBM_FLUSH\fR needs some processing. Because the read queue of one side is
38 -connected to the write queue of the other, the \fBFLUSHR\fR flag is changed to
39 -the \fBFLUSHW\fR flag and vice versa. When the master device is closed an
40 -\fBM_HANGUP\fR message is sent to the slave device which will render the device
41 -unusable. The process on the slave side gets the errno \fBEIO\fR when
42 -attempting to write on that stream but it will be able to read any data
43 -remaining on the stream head read queue. When all the data has been read,
44 -\fBread()\fR returns 0 indicating that the stream can no longer be used. On the
45 -last close of the slave device, a 0-length message is sent to the master
46 -device. When the application on the master side issues a \fBread()\fR or
47 -\fBgetmsg()\fR and 0 is returned, the user of the master device decides whether
48 -to issue a \fBclose()\fR that dismantles the pseudo-terminal subsystem. If the
49 -master device is not closed, the pseudo-tty subsystem will be available to
50 -another user to open the slave device.
51 -.sp
52 -.LP
53 -If \fBO_NONBLOCK\fR or \fBO_NDELAY\fR is set, read on the master side returns
54 -\(mi1 with errno set to \fBEAGAIN\fR if no data is available, and write returns
55 -\(mi1 with errno set to \fBEAGAIN\fR if there is internal flow control.
56 -.SH IOCTLS
57 -.sp
58 -.LP
59 -The master driver supports the \fBISPTM\fR and \fBUNLKPT\fR ioctls that are
60 -used by the functions \fBgrantpt\fR(3C), \fBunlockpt\fR(3C) and
61 -\fBptsname\fR(3C). The ioctl \fBISPTM\fR determines whether the file descriptor
62 -is that of an open master device. On success, it returns the 0. The ioctl
63 -\fBUNLKPT\fR unlocks the master and slave devices. It returns 0 on success. On
64 -failure, the errno is set to \fBEINVAL\fR indicating that the master device is
65 -not open.
66 -.SH FILES
67 -.sp
68 -.ne 2
69 -.na
70 -\fB\fB/dev/ptmx\fR\fR
71 -.ad
72 -.RS 14n
73 -master clone device
74 -.RE
75 -
76 -.sp
77 -.ne 2
78 -.na
79 -\fB\fB/dev/pts/M\fR\fR
80 -.ad
81 -.RS 14n
82 -slave devices (M = 0 -> N-1)
83 -.RE
84 -
85 -.SH SEE ALSO
86 -.sp
87 -.LP
88 -\fBgrantpt\fR(3C), \fBptsname\fR(3C), \fBunlockpt\fR(3C), \fBpckt\fR(7M),
89 -\fBpts\fR(7D)
90 -.sp
91 -.LP
92 -\fISTREAMS Programming Guide\fR
7 +.\" Copyright 2022 Oxide Computer Company
8 +.Dd February 5, 2022
9 +.Dt PTM 7D
10 +.Os
11 +.Sh NAME
12 +.Nm ptm ,
13 +.Nm pts
14 +.Nd STREAMS pseudo-terminal manager and subsidiary drivers
15 +.Sh SYNOPSIS
16 +.Pa /dev/ptmx
17 +.Pp
18 +.Pa /dev/pts/*
19 +.Sh DESCRIPTION
20 +The pseudo-terminal subsystem simulates a terminal connection, where the
21 +manager side represents the terminal and the subsidiary represents the user
22 +process's special device end point.
23 +The manager device is set up as a cloned device where its major device number
24 +is the major for the clone device and its minor device number is the major for
25 +the
26 +.Nm ptm
27 +driver; see
28 +.Dv CLONE_DEV
29 +in
30 +.Xr ddi_create_minor_node 9F .
31 +.Pp
32 +There are no nodes in the file system for manager devices.
33 +The manager pseudo driver is opened using the
34 +.Xr open 2
35 +system call with
36 +.Pa /dev/ptmx
37 +as the device parameter.
38 +The clone open finds the next available minor device for the
39 +.Nm ptm
40 +major device.
41 +.Pp
42 +A manager device is only available if it and its corresponding subsidiary
43 +device are not already open.
44 +Only one open is allowed on a manager device.
45 +Multiple opens are allowed on the subsidiary device.
46 +.Pp
47 +When the manager device is opened, the corresponding subsidiary device is
48 +automatically locked out.
49 +No user may open the subsidiary device until its permissions are adjusted and
50 +the device is unlocked by calling the functions
51 +.Xr grantpt 3C
52 +and
53 +.Xr unlockpt 3C .
54 +The user can then invoke the
55 +.Xr open 2
56 +system call with the device name returned by the
57 +.Xr ptsname 3C
58 +function.
59 +.Pp
60 +After both the manager and subsidiary have been opened, the user has two file
61 +descriptors which are the end points of a full duplex connection composed of
62 +two streams which are automatically connected at the manager and subsidiary
63 +drivers.
64 +The user may then push modules onto either side of the stream pair.
65 +Unless compiled in XPG4v2 mode
66 +.Po
67 +see
68 +.Sx "XPG4v2 MODE"
69 +.Pc ,
70 +the consumer needs to push the
71 +.Xr ptem 7M
72 +and
73 +.Xr ldterm 7M
74 +modules onto the subsidiary device to get terminal semantics.
75 +.Pp
76 +The manager and subsidiary drivers pass all messages to their adjacent queues.
77 +Only the
78 +.Dv M_FLUSH
79 +needs some processing.
80 +Because the read queue of one side is connected to the write queue of the
81 +other, the
82 +.Dv FLUSHR
83 +flag is changed to the
84 +.Dv FLUSHW
85 +flag and vice versa.
86 +.Pp
87 +When the manager device is closed, an
88 +.Dv M_HANGUP
89 +message is sent to the subsidiary device which will render the device unusable.
90 +The process on the subsidiary side gets an
91 +.Er EIO
92 +error when attempting to write on that stream, but it will be able to read
93 +any data remaining on the stream head read queue.
94 +When all the data has been read,
95 +.Xr read 2
96 +returns
97 +.Sy 0
98 +indicating that the stream can no longer be used.
99 +.Pp
100 +On the last close of the subsidiary device, a 0-length message is sent to the
101 +manager device.
102 +When the application on the manager side issues a
103 +.Xr read 2
104 +or
105 +.Xr getmsg 2
106 +and
107 +.Sy 0
108 +is returned, the user of the manager device decides whether to issue a
109 +.Xr close 2
110 +that dismantles the entire pseudo-terminal.
111 +If the manager device is not closed, the pseudo-terminal will be available to
112 +another user to open the subsidiary device.
113 +.Pp
114 +Since 0-length messages are used to indicate that the process on the
115 +subsidiary side has closed, and should be interpreted that way by the process
116 +on the manager side, applications on the subsidiary side should not write
117 +0-length messages.
118 +Unless the application is compiled in XPG4v2 mode
119 +.Po
120 +see
121 +.Sx "XPG4v2 MODE"
122 +.Pc ,
123 +then any 0-length messages written to the subsidiary device will be discarded
124 +by the
125 +.Xr ptem 7M
126 +module.
127 +.Pp
128 +If
129 +.Dv O_NONBLOCK
130 +or
131 +.Dv O_NDELAY
132 +is set on the manager side:
133 +.Bl -bullet
134 +.It
135 +Read on the manager side returns
136 +.Sy -1
137 +with
138 +.Va errno
139 +set to
140 +.Er EAGAIN
141 +if no data is available
142 +.It
143 +Write returns
144 +.Sy -1
145 +with
146 +.Va errno
147 +set to
148 +.Er EAGAIN
149 +if there is internal flow control
150 +.El
151 +.Pp
152 +Standard STREAMS system calls can access pseudo-terminal devices.
153 +The subsidiary devices support the
154 +.Dv O_NDELAY
155 +and
156 +.Dv O_NONBLOCK
157 +flags.
158 +.Sh XPG4v2 MODE
159 +.Em XPG4v2
160 +requires that subsidiary pseudo-terminal devices provide the process with an
161 +interface that is identical to the terminal interface, without needing to
162 +explicitly push any modules to achieve this.
163 +It also requires that 0-length messages written on the subsidiary device will
164 +be propagated to the manager device.
165 +.Pp
166 +Experience has shown that most software does not expect subsidiary
167 +pseudo-terminal devices to operate in this manner.
168 +This XPG4v2-compliant behaviour is only enabled in XPG4v2/SUS
169 +.Po
170 +see
171 +.Xr standards 5
172 +.Pc
173 +mode.
174 +.Sh IOCTLS
175 +The manager driver provides several ioctls to support the
176 +.Xr grantpt 3C ,
177 +.Xr unlockpt 3C ,
178 +and
179 +.Xr ptsname 3C
180 +functions:
181 +.Bl -tag -width Ds
182 +.It Dv ISPTM
183 +Determines whether the file descriptor is that of an open manager device.
184 +On success, it returns the value
185 +.Sy 0 .
186 +.It Dv UNLKPT
187 +Unlocks the manager and subsidiary devices.
188 +It returns
189 +.Sy 0
190 +on success.
191 +On failure,
192 +.Vt errno
193 +is set to
194 +.Vt EINVAL
195 +indicating that the manager device is not open.
196 +.El
197 +.Sh FILES
198 +.Bl -tag -width Pa
199 +.It Pa /dev/ptmx
200 +Pseudo-terminal manager clone device.
201 +.It Pa /dev/pts/N
202 +Pseudo-terminal subsidiary devices, where
203 +.Sy N
204 +is a non-negative integer.
205 +Located via calls to
206 +.Xr ptsname 3C .
207 +.El
208 +.Sh EXAMPLES
209 +.Sy Example 1
210 +Opening the manager and subsidiary device for a pseudo-terminal.
211 +.Bd -literal -offset Ds
212 +#include <stdlib.h>
213 +#include <sys/types.h>
214 +#include <sys/stat.h>
215 +#include <unistd.h>
216 +#include <stropts.h>
217 +#include <fcntl.h>
218 +#include <err.h>
219 +\&...
220 +int fdm, fds;
221 +char *subsidiaryname;
222 +\&...
223 +/*
224 + * NOTE: Portable applications should use posix_openpt(3C) here:
225 + */
226 +if ((fdm = open("/dev/ptmx", O_RDWR | O_NOCTTY)) < 0) {
227 + err(1, "open manager");
228 +}
229 +if (grantpt(fdm) != 0 || unlockpt(fdm) != 0 ||
230 + (subsidiaryname = ptsname(fdm)) == NULL) {
231 + close(fdm);
232 + err(1, "locate subsidiary");
233 +}
234 +if ((fds = open(subsidiaryname, O_RDWR | O_NOCTTY)) < 0) {
235 + close(fdm);
236 + err(1, "open subsidiary");
237 +}
238 +if (ioctl(fds, I_PUSH, "ptem") != 0 ||
239 + ioctl(fds, I_PUSH, "ldterm") != 0) {
240 + close(fds);
241 + close(fdm);
242 + err(1, "push modules");
243 +}
244 +.Ed
245 +.Sh SEE ALSO
246 +.Xr close 2 ,
247 +.Xr getmsg 2 ,
248 +.Xr open 2 ,
249 +.Xr read 2 ,
250 +.Xr grantpt 3C ,
251 +.Xr posix_openpt 3C ,
252 +.Xr ptsname 3C ,
253 +.Xr unlockpt 3C ,
254 +.Xr standards 5 ,
255 +.Xr ldterm 7M ,
256 +.Xr pckt 7M ,
257 +.Xr ptem 7M ,
258 +.Xr ddi_create_minor_node 9F
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX