| blob | bb25a01d1ecb3a1e04e5e04dca9d543dc6429600 |
1 '\" te
2 .\" Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 2001 AT&T
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 TTCOMPAT 7M "Oct 2, 2001"
8 .SH NAME
9 ttcompat \- V7, 4BSD and XENIX STREAMS compatibility module
10 .SH SYNOPSIS
11 .LP
12 .nf
13 #define BSD_COMP
14 #include <sys/stropts.h>
15 #include <sys/ioctl.h>
16 ioctl(\fIfd\fR, I_PUSH, "ttcompat");
17 .fi
19 .SH DESCRIPTION
20 .sp
21 .LP
22 \fBttcompat\fR is a STREAMS module that translates the \fBioctl\fR calls
23 supported by the older \fBVersion\fR \fB7,\fR \fB4BSD,\fR and \fBXENIX\fR
24 terminal drivers into the \fBioctl\fR calls supported by the \fBtermio\fR
25 interface (see \fBtermio\fR(7I)). All other messages pass through this module
26 unchanged; the behavior of \fBread\fR and \fBwrite\fR calls is unchanged, as is
27 the behavior of \fBioctl\fR calls other than the ones supported by
28 \fBttcompat\fR.
29 .sp
30 .LP
31 This module can be automatically pushed onto a stream using the \fBautopush\fR
32 mechanism when a terminal device is opened; it does not have to be explicitly
33 pushed onto a stream. This module requires that the \fBtermios\fR interface be
34 supported by the modules and the application can push the driver downstream.
35 The \fBTCGETS,\fR \fBTCSETS,\fR and \fBTCSETSF\fR \fBioctl\fR calls must be
36 supported. If any information set or fetched by those \fBioctl\fR calls is not
37 supported by the modules and driver downstream, some of the \fBV7/4BSD/XENIX\fR
38 functions may not be supported. For example, if the \fBCBAUD\fR bits in the
39 \fBc_cflag\fR field are not supported, the functions provided by the
40 \fBsg_ispeed\fR and \fBsg_ospeed\fR fields of the \fBsgttyb\fR structure (see
41 below) will not be supported. If the \fBTCFLSH\fR \fBioctl\fR is not supported,
42 the function provided by the \fBTIOCFLUSH\fR \fBioctl\fR will not be supported.
43 If the \fBTCXONC\fR \fBioctl\fR is not supported, the functions provided by the
44 \fBTIOCSTOP\fR and \fBTIOCSTART\fR \fBioctl\fR calls will not be supported. If
45 the \fBTIOCMBIS\fR and \fBTIOCMBIC\fR \fBioctl\fR calls are not supported, the
46 functions provided by the \fBTIOCSDTR\fR and \fBTIOCCDTR\fR \fBioctl\fR calls
47 will not be supported.
48 .sp
49 .LP
50 The basic \fBioctl\fR calls use the \fBsgttyb\fR structure defined by
51 <\fBsys/ttold.h\fR> (included by <\fBsys/ioctl.h\fR>):
52 .sp
53 .in +2
54 .nf
55 struct sgttyb {
56 char sg_ispeed;
57 char sg_ospeed;
58 char sg_erase;
59 char sg_kill;
60 int sg_flags;
61 };
62 .fi
63 .in -2
65 .sp
66 .LP
67 The \fBsg_ispeed\fR and \fBsg_ospeed\fR fields describe the input and output
68 speeds of the device. If the speed set on the device is over B38400, then it
69 is reported as B38400 for compatibility reasons. If it is set to B38400 and
70 the current speed is over B38400, the change is ignored. See TIOCGETP and
71 TIOCSETP below. The \fBsg_erase\fR and \fBsg_kill fields\fR of the argument
72 structure specify the erase and kill characters respectively, and reflect the
73 values in the VERASE and VKILL members of the \fBc_cc field\fR of the
74 \fBtermios\fR structure.
75 .sp
76 .LP
77 The \fBsg_flags\fR field of the argument structure contains several flags that
78 determine the system's treatment of the terminal. They are mapped into flags in
79 fields of the terminal state, represented by the \fBtermios\fR structure.
80 .sp
81 .LP
82 Delay type \fB0\fR (NL0, TAB0, CR0, FF0, BS0) is always mapped into the
83 equivalent delay type \fB0\fR in the \fBc_oflag\fR field of the \fBtermios\fR
84 structure. Other delay mappings are performed as follows:
85 .sp
87 .sp
88 .TS
89 box;
90 c | c
91 l | l .
92 sg_flags c_oflag
93 _
94 BS1 BS1
95 _
96 FF1 VT1
97 _
98 CR1 CR2
99 _
100 CR2 CR3
101 _
102 CR3 CR0 (not supported)
103 _
104 TAB1 TAB1
105 _
106 TAB2 TAB2
107 _
108 XTABS TAB3
109 _
110 NL1 ONLRET|CR1
111 _
112 NL2 NL1
113 _
114 NL3 NL0 (not supported)
115 .TE
117 .sp
118 .LP
119 If previous \fBTIOCLSET\fR or \fBTIOCLBIS\fR \fBioctl\fR calls have not
120 selected \fBLITOUT\fR or \fBPASS8\fR mode, and if \fBRAW\fR mode is not
121 selected, the \fBISTRIP\fR flag is set in the \fBc_iflag\fR field of the
122 \fBtermios\fR structure, and the \fBEVENP\fR and \fBODDP\fR flags control the
123 parity of characters sent to the terminal and accepted from the terminal, as
124 follows:
125 .sp
126 .ne 2
127 .na
128 \fB0 (neither EVENP nor ODDP)\fR
129 .ad
130 .RS 30n
131 Parity is not to be generated on output or checked on input. The character
132 size is set to \fBCS8\fR and the \fBPARENB\fR flag is cleared in the
133 \fBc_cflag\fR field of the \fBtermios\fR structure.
134 .RE
136 .sp
137 .ne 2
138 .na
139 \fBEVENP\fR
140 .ad
141 .RS 30n
142 Even parity characters are to be generated on output and accepted on input. The
143 INPCK flag is set in the \fBc_iflag\fR field of the \fBtermios\fR structure,
144 the character size is set to \fBCS7\fR and the \fBPARENB\fR flag is set in the
145 \fBc_iflag\fR field of the \fBtermios\fR structure.
146 .RE
148 .sp
149 .ne 2
150 .na
151 \fBODDP\fR
152 .ad
153 .RS 30n
154 Odd parity characters are to be generated on output and accepted on input. The
155 \fBINPCK\fR flag is set in the \fBc_iflag\fR, the character size is set to
156 \fBCS7\fR and the \fBPARENB\fR and \fBPARODD\fR flags are set in the
157 \fBc_iflag\fR field of the \fBtermios\fR structure.
158 .RE
160 .sp
161 .ne 2
162 .na
163 \fBEVENP|ODDP or ANYP\fR
164 .ad
165 .RS 30n
166 Even parity characters are to be generated on output and characters of
167 either parity are to be accepted on input. The \fBINPCK\fR flag is cleared in
168 the \fBc_iflag\fR field, the character size is set to \fBCS7\fR and the
169 \fBPARENB\fR flag is set in the \fBc_iflag\fR field of the \fBtermios\fR
170 structure.
171 .RE
173 .sp
174 .LP
175 The \fBRAW\fR flag disables all output processing (the \fBOPOST\fR flag in the
176 \fBc_oflag\fR field, and the \fBXCASE\fR and \fBIEXTEN\fR flags in the
177 \fBc_iflag\fR field are cleared in the termios structure) and input processing
178 (all flags in the \fBc_iflag\fR field other than the \fBIXOFF\fR and
179 \fBIXANY\fR flags are cleared in the \fBtermios\fR structure). Eight bits of
180 data, with no parity bit are accepted on input and generated on output; the
181 character size is set to \fBCS8\fR and the \fBPARENB\fR and \fBPARODD\fR flags
182 are cleared in the \fBc_cflag\fR field of the \fBtermios\fR structure. The
183 signal-generating and line-editing control characters are disabled by clearing
184 the \fBISIG\fR and \fBICANON\fR flags in the \fBc_iflag\fR field of the termios
185 structure.
186 .sp
187 .LP
188 The \fBCRMOD\fR flag turns input carriage return characters into linefeed
189 characters, and output linefeed characters to be sent as a carriage return
190 followed by a linefeed. The \fBICRNL\fR flag in the \fBc_iflag\fR field, and
191 the \fBOPOST\fR and \fBONLCR\fR flags in the \fBc_oflag field\fR, are set in
192 the termios structure.
193 .sp
194 .LP
195 The \fBLCASE\fR flag maps upper-case letters in the \fBASCII\fR character set
196 to their lower-case equivalents on input (the \fBIUCLC\fR flag is set in the
197 \fBc_iflag\fR field), and maps lower-case letters in the \fBASCII\fR character
198 set to their upper-case equivalents on output (the \fBOLCUC\fR flag is set in
199 the \fBc_oflag\fR field). Escape sequences are accepted on input, and generated
200 on output, to handle certain \fBASCII\fR characters not supported by older
201 terminals (the \fBXCASE\fR flag is set in the \fBc_lflag\fR field).
202 .sp
203 .LP
204 Other flags are directly mapped to flags in the \fBtermios\fR structure:
205 .sp
207 .sp
208 .TS
209 box;
210 c | c
211 l | l .
212 sg_flags Flags in termios structure
213 _
214 CBREAK Complement of ICANON in c_lflag field
215 _
216 ECHO ECHO in c_lflag field
217 _
218 TANDEM IXOFF in c_iflag field
219 .TE
221 .sp
222 .LP
223 Another structure associated with each terminal specifies characters that are
224 special in both the old Version 7 and the newer \fB4BSD\fR terminal interfaces.
225 The following structure is defined by \fB<sys/ttold.h>\fR:
226 .sp
227 .in +2
228 .nf
229 struct tchars {
230 char t_intrc; /* interrupt */
231 char t_quitc; /* quit */
232 char t_startc; /* start output */
233 char t_stopc; /* stop output */
234 char t_eofc; /* end-of-file */
235 char t_brkc; /* input delimiter (like nl) */
236 };
237 .fi
238 .in -2
240 .sp
241 .LP
242 \fBXENIX\fR defines the \fBtchar\fR structure as \fBtc\fR. The characters are
243 mapped to members of the \fBc_cc\fR field of the \fBtermios\fR structure as
244 follows:
245 .sp
246 .in +2
247 .nf
248 tchars c_cc index
249 t_intrc VINTR
250 t_quitc VQUIT
251 t_startc VSTART
252 t_stopc VSTOP
253 t_eofc VEOF
254 t_brkc VEOL
255 .fi
256 .in -2
258 .sp
259 .LP
260 Also associated with each terminal is a local flag word (\fBTIOCLSET\fR and
261 \fBTIOCLGET\fR), specifying flags supported by the new 4BSD terminal
262 interface. Most of these flags are directly mapped to flags in the
263 \fBtermios\fR structure:
264 .sp
266 .sp
267 .TS
268 box;
269 c | c
270 l | l .
271 Local flags Flags in termios structure
272 _
273 LCRTBS Not supported
274 _
275 LPRTERA ECHOPRT in the c_lflag field
276 _
277 LCRTERA ECHOE in the c_lflag field
278 _
279 LTILDE Not supported
280 _
281 LMDMBUF Not supported
282 _
283 LTOSTOP TOSTOP in the c_lflag field
284 _
285 LFLUSHO FLUSHO in the c_lflag field
286 _
287 LNOHANG CLOCAL in the c_cflag field
288 _
289 LCRTKIL ECHOKE in the c_lflag field
290 _
291 LPASS8 CS8 in the c_cflag field
292 _
293 LCTLECH CTLECH in the c_lflag field
294 _
295 LPENDIN PENDIN in the c_lflag field
296 _
297 LDECCTQ Complement of IXANY in the c_iflag field
298 _
299 LNOFLSH NOFLSH in the c_lflag field
300 .TE
302 .sp
303 .LP
304 Each flag has a corresponding equivalent \fBsg_flags\fR value. The
305 \fBsg_flags\fR definitions omit the leading "L"; for example, TIOCSETP with
306 \fBsg_flags\fR set to TOSTOP is equivalent to TIOCLSET with LTOSTOP.
307 .sp
308 .LP
309 Another structure associated with each terminal is the \fBltchars\fR structure
310 which defines control characters for the new \fB4BSD\fR terminal interface. Its
311 structure is:
312 .sp
313 .in +2
314 .nf
315 struct ltchars {
316 char t_suspc; /* stop process signal */
317 char t_dsuspc; /* delayed stop process signal */
318 char t_rprntc; /* reprint line */
319 char t_flushc; /*flush output (toggles) */
320 char t_werasc; /* word erase */
321 char t_lnextc; /* literal next character */
322 };
323 .fi
324 .in -2
326 .sp
327 .LP
328 The characters are mapped to members of the \fBc_cc\fR field of the
329 \fBtermios\fR structure as follows:
330 .sp
332 .sp
333 .TS
334 box;
335 c | c
336 l | l .
337 ltchars c_cc index
338 _
339 t_suspc VSUS
340 _
341 t_dsuspc VDSUSP
342 _
343 t_rprntc VREPRINT
344 _
345 t_flushc VDISCARD
346 _
347 t_werasc VWERASE
348 _
349 t_lnextc VLNEXT
350 .TE
352 .SH IOCTLS
353 .sp
354 .LP
355 \fBttcompat\fR responds to the following \fBioctl\fR calls. All others are
356 passed to the module below.
357 .sp
358 .ne 2
359 .na
360 \fB\fBTIOCGETP\fR \fR
361 .ad
362 .RS 14n
363 The argument is a pointer to an \fBsgttyb\fR structure. The current terminal
364 state is fetched; the appropriate characters in the terminal state are
365 stored in that structure, as are the input and output speeds. If the speed is
366 over B38400, then B38400 is returned. The values of the flags in the
367 \fBsg_flags\fR field are derived from the flags in the terminal state and
368 stored in the structure.
369 .RE
371 .sp
372 .ne 2
373 .na
374 \fB\fBTIOCEXCL\fR \fR
375 .ad
376 .RS 14n
377 Set ``exclusive-use'' mode; no further opens are permitted until the file has
378 been closed.
379 .RE
381 .sp
382 .ne 2
383 .na
384 \fB\fBTIOCNXCL\fR \fR
385 .ad
386 .RS 14n
387 Turn off ``exclusive-use'' mode.
388 .RE
390 .sp
391 .ne 2
392 .na
393 \fB\fBTIOCSETP\fR \fR
394 .ad
395 .RS 14n
396 The argument is a pointer to an \fBsgttyb\fR structure. The appropriate
397 characters and input and output speeds in the terminal state are set from the
398 values in that structure, and the flags in the terminal state are set to match
399 the values of the flags in the \fBsg_flags\fR field of that structure. The
400 state is changed with a \fBTCSETSF\fR \fBioctl\fR so that the interface delays
401 until output is quiescent, then throws away any unread characters, before
402 changing the modes. If the current device speed is over B38400 for either input
403 or output speed, and B38400 is specified through this interface for that speed,
404 the actual device speed is not changed. If the device speed is B38400 or lower
405 or if some speed other than B38400 is specified, then the actual speed
406 specified is set.
407 .RE
409 .sp
410 .ne 2
411 .na
412 \fB\fBTIOCSETN\fR \fR
413 .ad
414 .RS 14n
415 The argument is a pointer to an \fBsgttyb\fR structure. The terminal state is
416 changed as \fBTIOCSETP\fR would change it, but a \fBTCSETS\fR \fBioctl\fR is
417 used, so that the interface neither delays nor discards input.
418 .RE
420 .sp
421 .ne 2
422 .na
423 \fB\fBTIOCHPCL\fR \fR
424 .ad
425 .RS 14n
426 The argument is ignored. The \fBHUPCL\fR flag is set in the \fBc_cflag\fR word
427 of the terminal state.
428 .RE
430 .sp
431 .ne 2
432 .na
433 \fB\fBTIOCFLUSH\fR \fR
434 .ad
435 .RS 14n
436 The argument is a pointer to an \fBint\fR variable. If its value is zero, all
437 characters waiting in input or output queues are flushed. Otherwise, the value
438 of the \fBint\fR is treated as the logical \fBOR\fR of the \fBFREAD\fR and
439 \fBFWRITE\fR flags defined by \fB<sys/file.h>\fR\&. If the \fBFREAD\fR bit is
440 set, all characters waiting in input queues are flushed, and if the
441 \fBFWRITE\fR bit is set, all characters waiting in output queues are flushed.
442 .RE
444 .sp
445 .ne 2
446 .na
447 \fB\fBTIOCSBRK\fR \fR
448 .ad
449 .RS 14n
450 The argument is ignored. The break bit is set for the device. (This is not
451 supported by \fBttcompat\fR. The underlying driver must support TIOCSBRK.)
452 .RE
454 .sp
455 .ne 2
456 .na
457 \fB\fBTIOCCBRK\fR \fR
458 .ad
459 .RS 14n
460 The argument is ignored. The break bit is cleared for the device. (This is not
461 supported by \fBttcompat\fR. The underlying driver must support TIOCCBRK.)
462 .RE
464 .sp
465 .ne 2
466 .na
467 \fB\fBTIOCSDTR\fR \fR
468 .ad
469 .RS 14n
470 The argument is ignored. The Data Terminal Ready bit is set for the device.
471 .RE
473 .sp
474 .ne 2
475 .na
476 \fB\fBTIOCCDTR\fR \fR
477 .ad
478 .RS 14n
479 The argument is ignored. The Data Terminal Ready bit is cleared for the device.
480 .RE
482 .sp
483 .ne 2
484 .na
485 \fB\fBTIOCSTOP\fR \fR
486 .ad
487 .RS 14n
488 The argument is ignored. Output is stopped as if the \fBSTOP\fR character had
489 been typed.
490 .RE
492 .sp
493 .ne 2
494 .na
495 \fB\fBTIOCSTART\fR \fR
496 .ad
497 .RS 14n
498 The argument is ignored. Output is restarted as if the \fBSTART\fR character
499 had been typed.
500 .RE
502 .sp
503 .ne 2
504 .na
505 \fB\fBTIOCGETC\fR \fR
506 .ad
507 .RS 14n
508 The argument is a pointer to a \fBtchars\fR structure. The current terminal
509 state is fetched, and the appropriate characters in the terminal state are
510 stored in that structure.
511 .RE
513 .sp
514 .ne 2
515 .na
516 \fB\fBTIOCSETC\fR \fR
517 .ad
518 .RS 14n
519 The argument is a pointer to a \fBtchars\fR structure. The values of the
520 appropriate characters in the terminal state are set from the characters in
521 that structure.
522 .RE
524 .sp
525 .ne 2
526 .na
527 \fB\fBTIOCLGET\fR \fR
528 .ad
529 .RS 14n
530 The argument is a pointer to an \fBint\fR. The current terminal state is
531 fetched, and the values of the local flags are derived from the flags in the
532 terminal state and stored in the \fBint\fR pointed to by the argument.
533 .RE
535 .sp
536 .ne 2
537 .na
538 \fB\fBTIOCLBIS\fR \fR
539 .ad
540 .RS 14n
541 The argument is a pointer to an \fBint\fR whose value is a mask containing
542 flags to be set in the local flags word. The current terminal state is fetched,
543 and the values of the local flags are derived from the flags in the terminal
544 state; the specified flags are set, and the flags in the terminal state are set
545 to match the new value of the local flags word.
546 .RE
548 .sp
549 .ne 2
550 .na
551 \fB\fBTIOCLBIC\fR \fR
552 .ad
553 .RS 14n
554 The argument is a pointer to an \fBint\fR whose value is a mask containing
555 flags to be cleared in the local flags word. The current terminal state is
556 fetched, and the values of the local flags are derived from the flags in the
557 terminal state; the specified flags are cleared, and the flags in the terminal
558 state are set to match the new value of the local flags word.
559 .RE
561 .sp
562 .ne 2
563 .na
564 \fB\fBTIOCLSET\fR \fR
565 .ad
566 .RS 14n
567 The argument is a pointer to an int containing a new set of local flags. The
568 flags in the terminal state are set to match the new value of the local flags
569 word. (This \fBioctl\fR was added because \fBsg_flags\fR was once a 16 bit
570 value. The local modes controlled by TIOCLSET are equivalent to the modes
571 controlled by TIOCSETP and \fBsg_flags\fR.)
572 .RE
574 .sp
575 .ne 2
576 .na
577 \fB\fBTIOCGLTC\fR \fR
578 .ad
579 .RS 14n
580 The argument is a pointer to an \fBltchars\fR structure. The values of the
581 appropriate characters in the terminal state are stored in that structure.
582 .RE
584 .sp
585 .ne 2
586 .na
587 \fB\fBTIOCSLTC\fR \fR
588 .ad
589 .RS 14n
590 The argument is a pointer to an \fBltchars\fR structure. The values of the
591 appropriate characters in the terminal state are set from the characters in
592 that structure.
593 .RE
595 .sp
596 .ne 2
597 .na
598 \fB\fBFIORDCHK\fR \fR
599 .ad
600 .RS 14n
601 Returns the number of immediately readable characters. The argument is ignored.
602 (This ioctl is handled in the stream head, not in the \fBttcompat\fR module.)
603 .RE
605 .sp
606 .ne 2
607 .na
608 \fB\fBFIONREAD\fR \fR
609 .ad
610 .RS 14n
611 Returns the number of immediately readable characters in the int pointed to by
612 the argument. (This ioctl is handled in the stream head, not in the
613 \fBttcompat\fR module.)
614 .RE
616 .sp
617 .LP
618 The following ioctls are returned as successful for the sake of compatibility.
619 However, nothing significant is done (that is, the state of the terminal is not
620 changed in any way, and no message is passed through to the underlying
621 \fBtty\fR driver).
622 .sp
623 .in +2
624 .nf
626 DIOCSETP
627 DIOCSETP
628 DIOCGETP
629 LDCLOSE
630 LDCHG
631 LDOPEN
632 LDGETT
633 LDSETT
634 TIOCGETD
635 TIOCSETD
636 .fi
637 .in -2
639 .sp
640 .LP
641 The following old \fBioctl\fRs are not supported by \fBttcompat\fR, but are
642 supported by Solaris \fBtty\fR drivers. As with all ioctl not otherwise listed
643 in this documentation, these are passed through to the underlying driver and
644 are handled there.
645 .sp
646 .in +2
647 .nf
648 TIOCREMOTE
649 TIOCGWINSZ
650 TIOCSWINSZ
651 .fi
652 .in -2
654 .sp
655 .LP
656 The following \fBioctls\fR are not supported by \fBttcompat\fR, and are
657 generally not supported by Solaris \fBtty\fR drivers. They are passed through,
658 and the \fBtty\fR drivers return EINVAL.
659 .sp
660 .in +2
661 .nf
662 LDSMAP
663 LDGMAP
664 LDNMAP
665 TIOCNOTTY
666 TIOCOUTQ
667 .fi
668 .in -2
670 .sp
671 .LP
672 (Note: LDSMAP, LDGMAP, and LDNMAP are defined in
673 <\fBsys/termios.h\fR>.)
674 .SH SEE ALSO
675 .sp
676 .LP
677 \fBioctl\fR(2), \fBtermios\fR(3C), \fBldterm\fR(7M), \fBtermio\fR(7I)