1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
|
'\" te
.\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
.\" Copyright 1992 Sun Microsystems
.\" 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.
.\" 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.
.\" 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]
.TH PTS 7D "Feb 29, 2020"
.SH NAME
pts \- STREAMS pseudo-tty slave driver
.SH DESCRIPTION
The pseudo-tty subsystem simulates a terminal connection, where the master side
represents the terminal and the slave represents the user process's special
device end point. In order to use the pseudo-tty subsystem, a node for the
master side driver \fB/dev/ptmx\fR and N nodes for the slave driver (N is
determined at installation time) must be installed. The names of the slave
devices are \fB/dev/pts/M\fR where \fBM\fR has the values 0 through N-1. When
the master device is opened, the corresponding slave device is automatically
locked out. No user may open that slave device until its permissions are
adjusted and the device unlocked by calling functions \fBgrantpt\fR(3C) and
\fBunlockpt\fR(3C). The user can then invoke the open system call with the name
that is returned by the \fBptsname\fR(3C) function. See the example below.
.sp
.LP
Only one open is allowed on a master device. Multiple opens are allowed on the
slave device. After both the master and slave have been opened, the user has
two file descriptors which are end points of a full duplex connection composed
of two streams automatically connected at the master and slave drivers. The
user may then push modules onto either side of the stream pair. Unless compiled
in XPG4v2 mode (see below), the consumer needs to push the \fBptem\fR(7M) and
\fBldterm\fR(7M) modules onto the slave side of the pseudo-terminal subsystem
to get terminal semantics.
.sp
.LP
The master and slave drivers pass all messages to their adjacent queues. Only
the \fBM_FLUSH\fR needs some processing. Because the read queue of one side is
connected to the write queue of the other, the \fBFLUSHR\fR flag is changed to
the \fBFLUSHW\fR flag and vice versa. When the master device is closed an
\fBM_HANGUP\fR message is sent to the slave device which will render the device
unusable. The process on the slave side gets the errno \fBEIO\fR when
attempting to write on that stream but it will be able to read any data
remaining on the stream head read queue. When all the data has been read, read
returns 0 indicating that the stream can no longer be used. On the last close
of the slave device, a 0-length message is sent to the master device. When the
application on the master side issues a \fBread()\fR or \fBgetmsg()\fR and 0 is
returned, the user of the master device decides whether to issue a
\fBclose()\fR that dismantles the pseudo-terminal subsystem. If the master
device is not closed, the pseudo-tty subsystem will be available to another
user to open the slave device. Since 0-length messages are used to indicate
that the process on the slave side has closed and should be interpreted that
way by the process on the master side, applications on the slave side should
not write 0-length messages. Unless the application is compiled in XPG4v2 mode
(see below) then any 0-length messages written on the slave side will be
discarded by the \fBptem\fR module.
.sp
.LP
The standard STREAMS system calls can access the pseudo-tty devices. The slave
devices support the \fBO_NDELAY\fR and \fBO_NONBLOCK\fR flags.
.SH XPG4v2 MODE
XPG4v2 requires that open of a slave pseudo terminal device provides the
process with an interface that is identical to the terminal interface (without
having to explicitly push any modules to achieve this). It also requires that
0-length messages written on the slave side will be propagated to the master.
.sp
Experience has shown, however, that most software does not expect slave pty
devices to operate in this manner and therefore this XPG4v2-compliant
behaviour is only enabled in XPG4v2/SUS (see \fBstandards\fR(5)) mode.
.SH EXAMPLES
.in +2
.nf
int fdm fds;
char *slavename;
extern char *ptsname();
fdm = open("/dev/ptmx", O_RDWR); /* open master */
grantpt(fdm); /* change permission of slave */
unlockpt(fdm); /* unlock slave */
slavename = ptsname(fdm); /* get name of slave */
fds = open(slavename, O_RDWR); /* open slave */
ioctl(fds, I_PUSH, "ptem"); /* push ptem */
ioctl(fds, I_PUSH, "ldterm"); /* push ldterm*/
.fi
.in -2
.SH FILES
.ne 2
.na
\fB\fB/dev/ptmx\fR\fR
.ad
.RS 14n
master clone device
.RE
.sp
.ne 2
.na
\fB\fB/dev/pts/M\fR\fR
.ad
.RS 14n
slave devices (M = 0 -> N-1)
.RE
.SH SEE ALSO
\fBgrantpt\fR(3C), \fBptsname\fR(3C), \fBunlockpt\fR(3C), \fBldterm\fR(7M),
\fBptm\fR(7D), \fBptem\fR(7M), \fBstandards\fR(5)
.sp
.LP
\fISTREAMS Programming Guide\fR
|
