| blob | 409ee23762b5d6288923b1cbaadcda0d3108181c |
1 '\" te
2 .\" Copyright 1989 AT&T
3 .\" Copyright (C) 1999, Sun Microsystems, Inc. All Rights Reserved
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 .\" 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 .\" 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 LDTERM 7M "Jun 7, 1999"
8 .SH NAME
9 ldterm \- standard STREAMS terminal line discipline module
10 .SH SYNOPSIS
11 .LP
12 .nf
13 #include <sys/stream.h>
14 .fi
16 .LP
17 .nf
18 #include <sys/termios.h>
19 .fi
21 .LP
22 .nf
23 int ioctl(\fIfd\fR,I_PUSH,"ldterm");
24 .fi
26 .SH DESCRIPTION
27 .sp
28 .LP
29 The \fBldterm\fR STREAMS module provides most of the \fBtermio\fR(7I) terminal
30 interface. The \fBvis \fRmodule does not perform the low-level device control
31 functions specified by flags in the \fBc_cflag\fR word of the
32 \fBtermio/termios\fR structure, or by the \fBIGNBRK\fR, \fBIGNPAR\fR,
33 \fBPARMRK\fR, or \fBINPCK\fR flags in the \fBc_iflag\fR word of the
34 \fBtermio/termios\fR structure. Those functions must be performed by the
35 driver or by modules pushed below the \fBldterm\fR module. \fBThe \fR\fBldterm
36 module\fR performs all other \fBtermio/termios\fR functions, though some may
37 require the cooperation of the driver or modules pushed below \fBldterm\fR and
38 may not be performed in some cases. These include the \fBIXOFF\fR flag in the
39 \fBc_iflag\fR word and the delays specified in the \fBc_oflag\fR word.
40 .sp
41 .LP
42 \fBThe \fR\fBldterm module\fR also handles single and multi-byte characters
43 from various codesets including both Extended Unix Code (\fBEUC\fR) and non-EUC
44 codesets.
45 .sp
46 .LP
47 The remainder of this section describes the processing of various \fBSTREAMS\fR
48 messages on the read- and write-side.
49 .SS "Read-side Behavior"
50 .sp
51 .LP
52 Various types of STREAMS messages are processed as follows:
53 .sp
54 .ne 2
55 .na
56 \fB\fBM_BREAK\fR \fR
57 .ad
58 .RS 12n
59 Depending on the state of the \fBBRKINT\fR flag, either an interrupt signal is
60 generated or the message is treated as if it were an \fBM_DATA\fR message
61 containing a single \fBASCII NUL\fR character when this message is received.
62 .RE
64 .sp
65 .ne 2
66 .na
67 \fB\fBM_DATA\fR \fR
68 .ad
69 .RS 12n
70 This message is normally processed using the standard \fBtermio\fR input
71 processing. If the \fBICANON\fR flag is set, a single input record (``line'')
72 is accumulated in an internal buffer and sent upstream when a line-terminating
73 character is received. If the \fBICANON\fR flag is not set, other input
74 processing is performed and the processed data are passed upstream.
75 .sp
76 If output is to be stopped or started as a result of the arrival of characters
77 (usually \fBCNTRL-Q\fR and \fBCNTRL-S),\fR \fBM_STOP\fR and \fBM_START\fR
78 messages are sent downstream. If the \fBIXOFF\fR flag is set and input is to be
79 stopped or started as a result of flow-control considerations, \fBM_STOPI\fR
80 and \fBM_STARTI\fR messages are sent downstream.
81 .sp
82 \fBM_DATA\fR messages are sent downstream, as necessary, to perform echoing.
83 .sp
84 If a signal is to be generated, an \fBM_FLUSH\fR message with a flag byte of
85 \fBFLUSHR\fR is placed on the read queue. If the signal is also to flush
86 output, an \fBM_FLUSH\fR message with a flag byte of \fBFLUSHW\fR is sent
87 downstream.
88 .RE
90 .sp
91 .LP
92 All other messages are passed upstream unchanged.
93 .SS "Write-side Behavior"
94 .sp
95 .LP
96 Various types of \fBSTREAMS\fR messages are processed as follows:
97 .sp
98 .ne 2
99 .na
100 \fB\fBM_FLUSH\fR \fR
101 .ad
102 .RS 13n
103 The write queue of the module is flushed of all its data messages and the
104 message is passed downstream.
105 .RE
107 .sp
108 .ne 2
109 .na
110 \fB\fBM_IOCTL\fR \fR
111 .ad
112 .RS 13n
113 The function of this \fBioctl\fR is performed and the message is passed
114 downstream in most cases. The \fBTCFLSH\fR and \fBTCXONC\fR \fBioctls\fR can
115 be performed entirely in the \fBldterm\fR module, so the reply is sent
116 upstream and the message is not passed downstream.
117 .RE
119 .sp
120 .ne 2
121 .na
122 \fB\fBM_DATA\fR \fR
123 .ad
124 .RS 13n
125 If the \fBOPOST\fR flag is set, or both the \fBXCASE\fR and \fBICANON\fR flags
126 are set, output processing is performed and the processed message is passed
127 downstream along with any \fBM_DELAY\fR messages generated. Otherwise, the
128 message is passed downstream without change.
129 .RE
131 .sp
132 .ne 2
133 .na
134 \fB\fBM_CTL\fR \fR
135 .ad
136 .RS 13n
137 If the size of the data buffer associated with the message is the size of
138 \fBstruct iocblk\fR, \fBldterm\fR will perform functional negotiation to
139 determine where the \fBtermio\fR(7I) processing is to be done. If the command
140 field of the \fBiocblk\fR structure (\fBioc_cmd\fR) is set to
141 \fBMC_NO_CANON\fR, the input canonical processing normally performed on
142 \fBM_DATA\fR messages is disabled and those messages are passed upstream
143 unmodified. (This is for the use of modules or drivers that perform their own
144 input processing, such as a pseudo-terminal in \fBTIOCREMOTE\fR mode connected
145 to a program that performs this processing). If the command is
146 \fBMC_DO_CANON\fR, all input processing is enabled. If the command is
147 \fBMC_PART_CANON\fR, then an \fBM_DATA\fR message containing a \fBtermios\fR
148 structure is expected to be attached to the original \fBM_CTL\fR message. The
149 \fBldterm\fR module will examine the \fBiflag\fR, \fBoflag\fR, and
150 \fB\fR\fBlflag\fR fields of the \fBtermios\fR structure and from that point on,
151 will process only those flags that have not been turned \fBON.\fR If none of
152 the above commands are found, the message is ignored. In any case, the message
153 is passed upstream.
154 .RE
156 .sp
157 .ne 2
158 .na
159 \fB\fBM_FLUSH\fR \fR
160 .ad
161 .RS 13n
162 The read queue of the module is flushed of all its data messages and all data
163 in the record being accumulated are also flushed. The message is passed
164 upstream.
165 .RE
167 .sp
168 .ne 2
169 .na
170 \fB\fBM_IOCACK\fR \fR
171 .ad
172 .RS 13n
173 The data contained within the message, which is to be returned to the process,
174 are augmented if necessary, and the message is passed upstream.
175 .RE
177 .sp
178 .LP
179 All other messages are passed downstream unchanged.
180 .SH IOCTLS
181 .sp
182 .LP
183 \fBThe \fR\fBldterm module\fR processes the following \fBTRANSPARENT\fR
184 ioctls. All others are passed downstream.
185 .sp
186 .ne 2
187 .na
188 \fB\fBTCGETS/TCGETA\fR \fR
189 .ad
190 .sp .6
191 .RS 4n
192 The message is passed downstream. If an acknowledgment is seen, the data
193 provided by the driver and modules downstream are augmented and the
194 acknowledgement is passed upstream.
195 .RE
197 .sp
198 .ne 2
199 .na
200 \fB\fBTCSETS/TCSETSW/TCSETSF/TCSETA/TCSETAW/TCSETAF\fR \fR
201 .ad
202 .sp .6
203 .RS 4n
204 The parameters that control the behavior of the \fBldterm\fR module are
205 changed. If a mode change requires options at the stream head to be changed, an
206 \fBM_SETOPTS\fR message is sent upstream. If the \fBICANON\fR flag is turned
207 on or off, the read mode at the stream head is changed to message-nondiscard or
208 byte-stream mode, respectively. If the \fBTOSTOP\fR flag is turned on or off,
209 the tostop mode at the stream head is turned on or off, respectively. In any
210 case, \fBldterm\fR passes the \fBioctl\fR on downstream for possible
211 additional processing.
212 .RE
214 .sp
215 .ne 2
216 .na
217 \fB\fBTCFLSH\fR \fR
218 .ad
219 .sp .6
220 .RS 4n
221 If the argument is 0, an \fBM_FLUSH\fR message with a flag byte of \fBFLUSHR\fR
222 is sent downstream and placed on the read queue. If the argument is 1, the
223 write queue is flushed of all its data messages and an \fBM_FLUSH\fR message
224 with a flag byte of \fBFLUSHW\fR is sent upstream and downstream. If the
225 argument is 2, the write queue is flushed of all its data messages and an
226 \fBM_FLUSH\fR message with a flag byte of \fBFLUSHRW\fR is sent downstream and
227 placed on the read queue.
228 .RE
230 .sp
231 .ne 2
232 .na
233 \fB\fBTCXONC\fR \fR
234 .ad
235 .sp .6
236 .RS 4n
237 If the argument is 0 and output is not already stopped, an \fBM_STOP\fR message
238 is sent downstream. If the argument is 1 and output is stopped, an
239 \fBM_START\fR message is sent downstream. If the argument is 2 and input is
240 not already stopped, an \fBM_STOPI\fR message is sent downstream. If the
241 argument is 3 and input is stopped, an \fBM_STARTI\fR message is sent
242 downstream.
243 .RE
245 .sp
246 .ne 2
247 .na
248 \fB\fBTCSBRK\fR \fR
249 .ad
250 .sp .6
251 .RS 4n
252 The message is passed downstream, so the driver has a chance to drain the data
253 and then send an \fBM_IOCACK\fR message upstream.
254 .RE
256 .sp
257 .ne 2
258 .na
259 \fB\fBEUC_WSET\fR \fR
260 .ad
261 .sp .6
262 .RS 4n
263 This call takes a pointer to an \fBeucioc\fR structure, and uses it to set the
264 \fBEUC\fR line discipline's local definition for the code set widths to be used
265 for subsequent operations. Within the stream, the line discipline may
266 optionally notify other modules of this setting using \fBM_CTL\fR messages.
267 When this call is received and the \fBeucioc\fRstructure contains valid data,
268 the line discipline changes into \fBEUC \fRhandling mode once the
269 \fBeucioc\fRdata is completely transferred to an internal data structure.
270 .RE
272 .sp
273 .ne 2
274 .na
275 \fB\fBEUC_WGET\fR \fR
276 .ad
277 .sp .6
278 .RS 4n
279 This call takes a pointer to an \fBeucioc\fR structure, and returns in it the
280 \fBEUC\fR code set widths currently in use by the \fBEUC\fR line discipline. If
281 the current codeset of the line discipline is not an \fBEUC\fR one, the result
282 is meaningless.
283 .RE
285 .SH SEE ALSO
286 .sp
287 .LP
288 \fBtermios\fR(3C), \fBconsole\fR(7D), \fBtermio\fR(7I)
289 .sp
290 .LP
291 \fISTREAMS Programming Guide\fR