Commit | Line | Data |
---|---|---|
15637ed4 RG |
1 | .\" Copyright (c) 1983, 1991 Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
4 | .\" Redistribution and use in source and binary forms, with or without | |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
12 | .\" 3. All advertising materials mentioning features or use of this software | |
13 | .\" must display the following acknowledgement: | |
14 | .\" This product includes software developed by the University of | |
15 | .\" California, Berkeley and its contributors. | |
16 | .\" 4. Neither the name of the University nor the names of its contributors | |
17 | .\" may be used to endorse or promote products derived from this software | |
18 | .\" without specific prior written permission. | |
19 | .\" | |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
30 | .\" SUCH DAMAGE. | |
31 | .\" | |
32 | .\" @(#)pty.4 6.3 (Berkeley) 3/28/91 | |
33 | .\" | |
34 | .Dd March 28, 1991 | |
35 | .Dt PTY 4 | |
36 | .Os BSD 4.2 | |
37 | .Sh NAME | |
38 | .Nm pty | |
39 | .Nd pseudo terminal driver | |
40 | .Sh SYNOPSIS | |
41 | .Nm pseudo-device pty | |
42 | .Op Ar count | |
43 | .Sh DESCRIPTION | |
44 | The | |
45 | .Xr pty | |
46 | driver provides support for a device-pair termed a | |
47 | .Em pseudo terminal . | |
48 | A pseudo terminal is a pair of character devices, a | |
49 | .Em master | |
50 | device and a | |
51 | .Em slave | |
52 | device. The slave device provides processes | |
53 | an interface identical | |
54 | to that described in | |
55 | .Xr tty 4 . | |
56 | However, whereas all other devices which provide the | |
57 | interface described in | |
58 | .Xr tty 4 | |
59 | have a hardware device of some sort behind them, the slave | |
60 | device has, instead, another process manipulating | |
61 | it through the master half of the pseudo terminal. | |
62 | That is, anything written on the master device is | |
63 | given to the slave device as input and anything written | |
64 | on the slave device is presented as input on the master | |
65 | device. | |
66 | .Pp | |
67 | In configuring, if an optional | |
68 | .Ar count | |
69 | is given in | |
70 | the specification, that number of pseudo terminal pairs are configured; | |
71 | the default count is 32. | |
72 | .Pp | |
73 | The following | |
74 | .Xr ioctl 2 | |
75 | calls apply only to pseudo terminals: | |
76 | .Bl -tag -width TIOCREMOTE | |
77 | .It Dv TIOCSTOP | |
78 | Stops output to a terminal (e.g. like typing | |
79 | .Ql ^S ) . | |
80 | Takes | |
81 | no parameter. | |
82 | .It Dv TIOCSTART | |
83 | Restarts output (stopped by | |
84 | .Dv TIOCSTOP | |
85 | or by typing | |
86 | .Ql ^S ) . | |
87 | Takes no parameter. | |
88 | .It Dv TIOCPKT | |
89 | Enable/disable | |
90 | .Em packet | |
91 | mode. Packet mode is enabled by specifying (by reference) | |
92 | a nonzero parameter and disabled by specifying (by reference) | |
93 | a zero parameter. When applied to the master side of a pseudo | |
94 | terminal, each subsequent | |
95 | .Xr read | |
96 | from the terminal will return data written on the slave part of | |
97 | the pseudo terminal preceded by a zero byte (symbolically | |
98 | defined as | |
99 | .Dv TIOCPKT_DATA ) , | |
100 | or a single byte reflecting control | |
101 | status information. In the latter case, the byte is an inclusive-or | |
102 | of zero or more of the bits: | |
103 | .Bl -tag -width TIOCPKT_FLUSHWRITE | |
104 | .It Dv TIOCPKT_FLUSHREAD | |
105 | whenever the read queue for the terminal is flushed. | |
106 | .It Dv TIOCPKT_FLUSHWRITE | |
107 | whenever the write queue for the terminal is flushed. | |
108 | .It Dv TIOCPKT_STOP | |
109 | whenever output to the terminal is stopped a la | |
110 | .Ql ^S . | |
111 | .It Dv TIOCPKT_START | |
112 | whenever output to the terminal is restarted. | |
113 | .It Dv TIOCPKT_DOSTOP | |
114 | whenever | |
115 | .Em t_stopc | |
116 | is | |
117 | .Ql ^S | |
118 | and | |
119 | .Em t_startc | |
120 | is | |
121 | .Ql ^Q . | |
122 | .It Dv TIOCPKT_NOSTOP | |
123 | whenever the start and stop characters are not | |
124 | .Ql ^S/^Q . | |
125 | .Pp | |
126 | While this mode is in use, the presence of control status information | |
127 | to be read from the master side may be detected by a | |
128 | .Xr select 2 | |
129 | for exceptional conditions. | |
130 | .Pp | |
131 | This mode is used by | |
132 | .Xr rlogin 1 | |
133 | and | |
134 | .Xr rlogind 8 | |
135 | to implement a remote-echoed, locally | |
136 | .Ql ^S/^Q | |
137 | flow-controlled | |
138 | remote login with proper back-flushing of output; it can be | |
139 | used by other similar programs. | |
140 | .El | |
141 | .It Dv TIOCUCNTL | |
142 | Enable/disable a mode that allows a small number of simple user | |
143 | .Xr ioctl | |
144 | commands to be passed through the pseudo-terminal, | |
145 | using a protocol similar to that of | |
146 | .Dv TIOCPKT . | |
147 | The | |
148 | .Dv TIOCUCNTL | |
149 | and | |
150 | .Dv TIOCPKT | |
151 | modes are mutually exclusive. | |
152 | This mode is enabled from the master side of a pseudo terminal | |
153 | by specifying (by reference) | |
154 | a nonzero parameter and disabled by specifying (by reference) | |
155 | a zero parameter. | |
156 | Each subsequent | |
157 | .Xr read | |
158 | from the master side will return data written on the slave part of | |
159 | the pseudo terminal preceded by a zero byte, | |
160 | or a single byte reflecting a user control operation on the slave side. | |
161 | A user control command consists of a special | |
162 | .Xr ioctl | |
163 | operation with no data; the command is given as | |
164 | .Dv UIOCCMD Ns (n) , | |
165 | where | |
166 | .Ar n | |
167 | is a number in the range 1-255. | |
168 | The operation value | |
169 | .Ar n | |
170 | will be received as a single byte on the next | |
171 | .Xr read | |
172 | from the master side. | |
173 | The | |
174 | .Xr ioctl | |
175 | .Dv UIOCCMD Ns (0) | |
176 | is a no-op that may be used to probe for | |
177 | the existence of this facility. | |
178 | As with | |
179 | .Dv TIOCPKT | |
180 | mode, command operations may be detected with a | |
181 | .Xr select | |
182 | for exceptional conditions. | |
183 | .It Dv TIOCREMOTE | |
184 | A mode for the master half of a pseudo terminal, independent | |
185 | of | |
186 | .Dv TIOCPKT . | |
187 | This mode causes input to the pseudo terminal | |
188 | to be flow controlled and not input edited (regardless of the | |
189 | terminal mode). Each write to the control terminal produces | |
190 | a record boundary for the process reading the terminal. In | |
191 | normal usage, a write of data is like the data typed as a line | |
192 | on the terminal; a write of 0 bytes is like typing an end-of-file | |
193 | character. | |
194 | .Dv TIOCREMOTE | |
195 | can be used when doing remote line | |
196 | editing in a window manager, or whenever flow controlled input | |
197 | is required. | |
198 | .El | |
199 | .Sh FILES | |
200 | .Bl -tag -width /dev/tty[p-r][0-9a-f]x -compact | |
201 | .It Pa /dev/pty[p-r][0-9a-f] | |
202 | master pseudo terminals | |
203 | .It Pa /dev/tty[p-r][0-9a-f] | |
204 | slave pseudo terminals | |
205 | .El | |
206 | .Sh DIAGNOSTICS | |
207 | None. | |
208 | .Sh HISTORY | |
209 | The | |
210 | .Nm | |
211 | driver appeared in | |
212 | .Bx 4.2 . |