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.man.txt
+++ new/usr/src/man/man7d/pty.7d.man.txt
1 1 PTY(7D) Devices PTY(7D)
2 2
3 3 NAME
4 - pty - pseudo-terminal driver
4 + pty - legacy pseudo-terminal driver
5 5
6 -DESCRIPTION
7 - The pty driver provides support for a pair of devices collectively
8 - known as a pseudo-terminal. The two devices comprising a pseudo-
9 - terminal are known as a controller and a slave. The slave device
10 - distinguishes between the B0 baud rate and other baud rates specified
11 - in the c_cflag word of the termios structure, and the CLOCAL flag in
12 - that word. It does not support any of the other termio(7I) device
13 - control functions specified by flags in the c_cflag word of the termios
14 - structure and by the IGNBRK, IGNPAR, PARMRK, or INPCK flags in the
15 - c_iflag word of the termios structure, as these functions apply only to
16 - asynchronous serial ports. All other termio(7I) functions must be
17 - performed by STREAMS modules pushed atop the driver; when a slave
18 - device is opened, the ldterm(7M) and ttcompat(7M) STREAMS modules are
19 - automatically pushed on top of the stream, providing the standard
20 - termio(7I) interface.
6 +SYNOPSIS
7 + /dev/pty[p-r]*
21 8
9 + /dev/tty[p-r]*
22 10
23 - Instead of having a hardware interface and associated hardware that
24 - supports the terminal functions, the functions are implemented by
25 - another process manipulating the controller device of the pseudo-
26 - terminal.
11 +DESCRIPTION
12 + This driver provides support for legacy static pseudo-terminal devices.
13 + Modern software does not use this driver, preferring instead the STREAMS-
14 + based ptm(7D) and pts(7D) pseudo-terminal drivers, consumed through the
15 + portable posix_openpt(3C) interface.
27 16
17 + The pty driver provides support for a pair of devices collectively known
18 + as a pseudo-terminal. The two devices comprising a pseudo-terminal are
19 + known as a manager and a subsidiary. The subsidiary device distinguishes
20 + between the B0 baud rate and other baud rates specified in the c_cflag
21 + field of the termios structure, and the CLOCAL flag in that member. It
22 + does not support any of the other termio(7I) device control functions
23 + specified by flags in the c_cflag field of the termios structure and by
24 + the IGNBRK, IGNPAR, PARMRK, or INPCK flags in the c_iflag field of the
25 + termios structure, as these functions apply only to asynchronous serial
26 + ports. All other termio(7I) functions must be performed by STREAMS
27 + modules pushed atop the driver; when a subsidiary device is opened, the
28 + ldterm(7M) and ttcompat(7M) STREAMS modules are automatically pushed on
29 + top of the stream, providing the standard termio(7I) interface.
28 30
29 - The controller and the slave devices of the pseudo-terminal are tightly
30 - connected. Any data written on the controller device is given to the
31 - slave device as input, as though it had been received from a hardware
32 - interface. Any data written on the slave terminal can be read from the
33 - controller device (rather than being transmitted from a UAR).
31 + Instead of having a hardware interface and associated hardware that
32 + supports the terminal functions, the functions are implemented by another
33 + process manipulating the manager device of the pseudo-terminal.
34 34
35 + The manager and the subsidiary devices of the pseudo-terminal are tightly
36 + connected. Any data written on the manager device is given to the
37 + subsidiary device as input, as though it had been received from a
38 + hardware interface. Any data written on the subsidiary terminal can be
39 + read from the manager device (rather than being transmitted from a UAR).
35 40
36 - By default, 48 pseudo-terminal pairs are configured as follows:
41 + The driver is statically configured to provide 48 pseudo-terminal pairs.
42 + Software that requires dynamic pseudo-terminal devices, or a greater
43 + number of devices, must be converted to use ptm(7D).
37 44
38 - /dev/pty[p-r][0-9a-f] controller devices
39 - /dev/tty[p-r][0-9a-f] slave devices
40 -
41 -
42 45 IOCTLS
43 - The standard set of termio ioctls are supported by the slave device.
44 - None of the bits in the c_cflag word have any effect on the pseudo-
45 - terminal, except that if the baud rate is set to B0, it will appear to
46 - the process on the controller device as if the last process on the
47 - slave device had closed the line; thus, setting the baud rate to B0 has
48 - the effect of ``hanging up'' the pseudo-terminal, just as it has the
49 - effect of ``hanging up'' a real terminal.
46 + The standard set of termio(7I) ioctls are supported by the subsidiary
47 + device. None of the bits in the c_cflag field have any effect on the
48 + pseudo-terminal, except that if the baud rate is set to B0, it will
49 + appear to the process on the manager device as if the last process on the
50 + subsidiary device had closed the line; thus, setting the baud rate to B0
51 + has the effect of "hanging up" the pseudo-terminal, just as it has the
52 + effect of "hanging up" a real terminal.
50 53
54 + There is no notion of "parity" on a pseudo-terminal, so none of the flags
55 + in the c_iflag field that control the processing of parity errors have
56 + any effect. Similarly, there is no notion of a break, so none of the
57 + flags that control the processing of breaks, and none of the ioctls that
58 + generate breaks, have any effect.
51 59
52 - There is no notion of ``parity'' on a pseudo-terminal, so none of the
53 - flags in the c_iflag word that control the processing of parity errors
54 - have any effect. Similarly, there is no notion of a ``break'', so none
55 - of the flags that control the processing of breaks, and none of the
56 - ioctls that generate breaks, have any effect.
60 + Input flow control is automatically performed; a process that attempts to
61 + write to the manager device will be blocked if too much unconsumed data
62 + is buffered on the subsidiary device. The input flow control provided by
63 + the IXOFF flag in the c_iflag field is not supported.
57 64
65 + The delays specified in the c_oflag field are not supported.
58 66
59 - Input flow control is automatically performed; a process that attempts
60 - to write to the controller device will be blocked if too much
61 - unconsumed data is buffered on the slave device. The input flow
62 - control provided by the IXOFF flag in the c_iflag word is not
63 - supported.
67 + As there are no modems involved in a pseudo-terminal, the ioctls that
68 + return or alter the state of modem control lines are silently ignored.
64 69
70 + A few special ioctls are provided on the manager devices of pseudo-
71 + terminals to provide the functionality needed by applications programs to
72 + emulate real hardware interfaces:
65 73
66 - The delays specified in the c_oflag word are not supported.
74 + TIOCSTOP
75 + The argument is ignored. Output to the pseudo-terminal is
76 + suspended, as if a STOP character had been typed.
67 77
78 + TIOCSTART
79 + The argument is ignored. Output to the pseudo-terminal is
80 + restarted, as if a START character had been typed.
68 81
69 - As there are no modems involved in a pseudo-terminal, the ioctls that
70 - return or alter the state of modem control lines are silently ignored.
82 + TIOCPKT
83 + The argument is a pointer to an int. If the value of the int is
84 + non-zero, packet mode is enabled; if the value of the int is
85 + zero, packet mode is disabled. When a pseudo-terminal is in
86 + packet mode, each subsequent read(2) from the manager device will
87 + return data written on the subsidiary device preceded by a zero
88 + byte (symbolically defined as TIOCPKT_DATA), or a single byte
89 + reflecting control status information. In the latter case, the
90 + byte is an inclusive-or of zero or more of the bits:
71 91
92 + TIOCPKT_FLUSHREAD
93 + Whenever the read queue for the terminal is flushed.
72 94
73 - A few special ioctls are provided on the controller devices of pseudo-
74 - terminals to provide the functionality needed by applications programs
75 - to emulate real hardware interfaces:
95 + TIOCPKT_FLUSHWRITE
96 + Whenever the write queue for the terminal is flushed.
76 97
77 - TIOCSTOP
78 - The argument is ignored. Output to the pseudo-terminal is
79 - suspended, as if a STOP character had been typed.
98 + TIOCPKT_STOP
99 + Whenever output to the terminal is stopped using ^S.
80 100
101 + TIOCPKT_START
102 + Whenever output to the terminal is restarted.
81 103
82 - TIOCSTART
83 - The argument is ignored. Output to the pseudo-terminal is
84 - restarted, as if a START character had been typed.
104 + TIOCPKT_DOSTOP
105 + Whenever XON/XOFF flow control is enabled after being
106 + disabled; it is considered "enabled" when the IXON flag
107 + in the c_iflag field is set, the VSTOP member of the c_cc
108 + array is ^S and the VSTART member of the c_cc array is
109 + ^Q.
85 110
111 + TIOCPKT_NOSTOP
112 + Whenever XON/XOFF flow control is disabled after being
113 + enabled.
86 114
87 - TIOCPKT
88 - The argument is a pointer to an int. If the value of the
89 - int is non-zero, packet mode is enabled; if the value of
90 - the int is zero, packet mode is disabled. When a pseudo-
91 - terminal is in packet mode, each subsequent read(2) from
92 - the controller device will return data written on the
93 - slave device preceded by a zero byte (symbolically
94 - defined as TIOCPKT_DATA), or a single byte reflecting
95 - control status information. In the latter case, the byte
96 - is an inclusive-or of zero or more of the bits:
115 + TIOCREMOTE
116 + The argument is a pointer to an int. If the value of the int is
117 + non-zero, remote mode is enabled; if the value of the int is
118 + zero, remote mode is disabled. This mode can be enabled or
119 + disabled independently of packet mode. When a pseudo-terminal is
120 + in remote mode, input to the subsidiary device of the pseudo-
121 + terminal is flow controlled and not input edited (regardless of
122 + the mode the subsidiary side of the pseudo-terminal).
97 123
98 - TIOCPKT_FLUSHREAD
99 - whenever the read queue for the
100 - terminal is flushed.
124 + Each write to the manager device produces a record boundary for
125 + the process reading the subsidiary device. In normal usage, a
126 + write of data is like the data typed as a line on the terminal; a
127 + write of 0 bytes is like typing an EOF character. Note: this
128 + means that a process writing to a pseudo-terminal manager in
129 + remote mode must keep track of line boundaries, and write only
130 + one line at a time to the manager.
101 131
132 + If, for example, it were to buffer up several newline characters
133 + and write them to the manager with one write(2), it would appear
134 + to a process reading from the subsidiary as if a single line
135 + containing several newline characters had been typed (as if, for
136 + example, a user had typed the literal next (LNEXT) character
137 + before typing all but the last of those newline characters).
138 + Remote mode can be used when doing remote line editing in a
139 + window manager, or whenever flow controlled input is required.
102 140
103 - TIOCPKT_FLUSHWRITE
104 - whenever the write queue for the
105 - terminal is flushed.
106 -
107 -
108 - TIOCPKT_STOP
109 - whenever output to the terminal is
110 - stopped using ^S.
111 -
112 -
113 - TIOCPKT_START
114 - whenever output to the terminal is
115 - restarted.
116 -
117 -
118 - TIOCPKT_DOSTOP
119 - whenever XON/XOFF flow control is
120 - enabled after being disabled; it is
121 - considered ``enabled'' when the
122 - IXON flag in the c_iflag word is
123 - set, the VSTOP member of the c_cc
124 - array is ^S and the VSTART member
125 - of the c_cc array is ^Q.
126 -
127 -
128 - TIOCPKT_NOSTOP
129 - whenever XON/XOFF flow control is
130 - disabled after being enabled.
131 -
132 -
133 -
134 - TIOCREMOTE
135 - The argument is a pointer to an int. If the value of the
136 - int is non-zero, remote mode is enabled; if the value of
137 - the int is zero, remote mode is disabled. This mode can
138 - be enabled or disabled independently of packet mode. When
139 - a pseudo-terminal is in remote mode, input to the slave
140 - device of the pseudo-terminal is flow controlled and not
141 - input edited (regardless of the mode the slave side of
142 - the pseudo-terminal). Each write to the controller device
143 - produces a record boundary for the process reading the
144 - slave device. In normal usage, a write of data is like
145 - the data typed as a line on the terminal; a write of 0
146 - bytes is like typing an EOF character. Note: this means
147 - that a process writing to a pseudo-terminal controller in
148 - remote mode must keep track of line boundaries, and write
149 - only one line at a time to the controller. If, for
150 - example, it were to buffer up several NEWLINE characters
151 - and write them to the controller with one write(), it
152 - would appear to a process reading from the slave as if a
153 - single line containing several NEWLINE characters had
154 - been typed (as if, for example, a user had typed the
155 - LNEXT character before typing all but the last of those
156 - NEWLINE characters). Remote mode can be used when doing
157 - remote line editing in a window manager, or whenever flow
158 - controlled input is required.
159 -
160 -
161 -EXAMPLES
162 - #include <fcntl.h>
163 - #include <sys/termios.h>
164 -
165 - int fdm fds;
166 - fdm = open("/dev/ptyp0, O_RDWR); /* open master */
167 - fds = open("/dev/ttyp0, O_RDWR); /* open slave */
168 -
169 -
170 141 FILES
171 - /dev/pty[p-z][0-9a-f]
172 - pseudo-terminal controller devices
142 + /dev/pty[p-r][0-9a-f] Pseudo-terminal manager devices.
173 143
144 + /dev/tty[p-r][0-9a-f] Pseudo-terminal subsidiary devices.
174 145
175 - /dev/tty[p-z][0-9a-f]
176 - pseudo-terminal slave devices
177 -
178 -
179 146 SEE ALSO
180 - rlogin(1), rlogind(1M), ldterm(7M), termio(7I), ttcompat(7M),
147 + rlogin(1), rlogind(1M), posix_openpty(3C), ptm(7D), termio(7I),
148 + ldterm(7M), ttcompat(7M)
181 149
182 150 NOTES
183 - It is apparently not possible to send an EOT by writing zero bytes in
184 - TIOCREMOTE mode.
151 + This is a legacy device and should not be used by new software.
185 152
186 - August 8, 1994 PTY(7D)
153 + It is apparently not possible to send an EOT by writing zero bytes in
154 + TIOCREMOTE mode.
155 +
156 +illumos February 5, 2022 illumos
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX