path: root/usr/src/man/man7m/ttcompat.7m

'\" te
.\" Copyright (c) 2001, Sun Microsystems, Inc.  All Rights Reserved.
.\" Copyright 2001 AT&T
.\" 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 ttcompat 7M "2 Oct 2001" "SunOS 5.11" "STREAMS Modules"
.SH NAME
ttcompat \- V7, 4BSD and XENIX STREAMS compatibility module
.SH SYNOPSIS
.LP
.nf
#define BSD_COMP
#include <sys/stropts.h>
#include <sys/ioctl.h>
ioctl(\fIfd\fR, I_PUSH, "ttcompat");
.fi

.SH DESCRIPTION
.sp
.LP
\fBttcompat\fR is a STREAMS module that translates the \fBioctl\fR calls
supported by the older \fBVersion\fR \fB7,\fR \fB4BSD,\fR and \fBXENIX\fR
terminal drivers into the \fBioctl\fR calls supported by the \fBtermio\fR
interface (see \fBtermio\fR(7I)). All other messages pass through this module
unchanged; the behavior of \fBread\fR and \fBwrite\fR calls is unchanged, as is
the behavior of \fBioctl\fR calls other than the ones supported by
\fBttcompat\fR.
.sp
.LP
This module can be automatically pushed onto a stream using the \fBautopush\fR
mechanism when a terminal device is opened; it does not have to be explicitly
pushed onto a stream. This module requires that the \fBtermios\fR interface be
supported by the modules and the application can push the driver downstream.
The \fBTCGETS,\fR \fBTCSETS,\fR and \fBTCSETSF\fR \fBioctl\fR calls must be
supported. If any information set or fetched by those \fBioctl\fR calls is not
supported by the modules and driver downstream, some of the \fBV7/4BSD/XENIX\fR
functions may not be supported. For example, if the \fBCBAUD\fR bits in the
\fBc_cflag\fR field are not supported, the functions provided by the
\fBsg_ispeed\fR and \fBsg_ospeed\fR fields of the \fBsgttyb\fR structure (see
below) will not be supported. If the \fBTCFLSH\fR \fBioctl\fR is not supported,
the function provided by the \fBTIOCFLUSH\fR \fBioctl\fR will not be supported.
If the \fBTCXONC\fR \fBioctl\fR is not supported, the functions provided by the
\fBTIOCSTOP\fR and \fBTIOCSTART\fR \fBioctl\fR calls will not be supported. If
the \fBTIOCMBIS\fR and \fBTIOCMBIC\fR \fBioctl\fR calls are not supported, the
functions provided by the \fBTIOCSDTR\fR and \fBTIOCCDTR\fR \fBioctl\fR calls
will not be supported.
.sp
.LP
The basic \fBioctl\fR calls use the \fBsgttyb\fR structure defined by
<\fBsys/ttold.h\fR> (included by <\fBsys/ioctl.h\fR>):
.sp
.in +2
.nf
struct   sgttyb   {
	char	sg_ispeed;
	char	sg_ospeed;
	char	sg_erase;
	char	sg_kill;
	int	sg_flags;
};
.fi
.in -2

.sp
.LP
The \fBsg_ispeed\fR and \fBsg_ospeed\fR fields describe the  input and output
speeds of the device.  If the speed set on the device is  over B38400,  then it
is reported as B38400 for compatibility reasons. If it is set to B38400 and
the current speed is over B38400, the change is ignored. See TIOCGETP and
TIOCSETP below. The \fBsg_erase\fR and \fBsg_kill fields\fR of the argument
structure specify the erase and kill characters respectively, and reflect the
values in the VERASE and VKILL members of the \fBc_cc field\fR of the
\fBtermios\fR structure.
.sp
.LP
The \fBsg_flags\fR field of the argument structure contains several flags that
determine the system's treatment of the terminal. They are mapped into flags in
fields of the terminal state, represented by the \fBtermios\fR structure.
.sp
.LP
Delay type \fB0\fR (NL0,  TAB0, CR0, FF0,  BS0) is  always mapped into the
equivalent delay type \fB0\fR in the \fBc_oflag\fR field of the \fBtermios\fR
structure. Other delay  mappings are  performed as follows:
.sp

.sp
.TS
tab() box;
cw(0i) |cw(5.5i) 
lw(0i) |lw(5.5i) 
.
sg_flagsc_oflag
_
BS1BS1
_
FF1VT1
_
CR1CR2
_
CR2CR3
_
CR3CR0 (not supported)
_
TAB1TAB1
_
TAB2TAB2
_
XTABSTAB3
_
NL1ONLRET|CR1
_
NL2NL1
_
NL3NL0 (not supported)
.TE

.sp
.LP
If previous \fBTIOCLSET\fR or \fBTIOCLBIS\fR \fBioctl\fR calls have not
selected \fBLITOUT\fR or \fBPASS8\fR mode, and if \fBRAW\fR mode is not
selected, the \fBISTRIP\fR flag is set in the \fBc_iflag\fR field of the
\fBtermios\fR structure, and the \fBEVENP\fR and \fBODDP\fR flags control the
parity of characters sent to the terminal and accepted from the terminal, as
follows:
.sp
.ne 2
.mk
.na
\fB0 (neither EVENP nor ODDP)\fR
.ad
.RS 30n
.rt  
Parity is not to be generated on output or checked on input. The  character
size is set to \fBCS8\fR and the \fBPARENB\fR flag is cleared in the
\fBc_cflag\fR field of the \fBtermios\fR structure.
.RE

.sp
.ne 2
.mk
.na
\fBEVENP\fR
.ad
.RS 30n
.rt  
Even parity characters are to be generated on output and accepted on input. The
INPCK  flag is set in the \fBc_iflag\fR field of the \fBtermios\fR structure,
the character size is set to \fBCS7\fR and the \fBPARENB\fR flag is set in the
\fBc_iflag\fR field of the \fBtermios\fR structure.
.RE

.sp
.ne 2
.mk
.na
\fBODDP\fR
.ad
.RS 30n
.rt  
Odd parity characters are to be generated on output and accepted on input. The
\fBINPCK\fR flag is set in the \fBc_iflag\fR, the character size is set to
\fBCS7\fR and the \fBPARENB\fR and \fBPARODD\fR flags are set in the
\fBc_iflag\fR field  of the \fBtermios\fR structure.
.RE

.sp
.ne 2
.mk
.na
\fBEVENP|ODDP or ANYP\fR
.ad
.RS 30n
.rt  
Even parity  characters are to be generated  on output and characters of
either parity are to be  accepted on input. The \fBINPCK\fR flag is cleared in
the \fBc_iflag\fR field, the character size is set to \fBCS7\fR and the
\fBPARENB\fR flag is set in the \fBc_iflag\fR field of the \fBtermios\fR
structure.
.RE

.sp
.LP
The \fBRAW\fR flag disables all output processing (the \fBOPOST\fR flag in the
\fBc_oflag\fR field, and the \fBXCASE\fR and \fBIEXTEN\fR flags in the
\fBc_iflag\fR field are cleared in the termios structure) and input processing
(all flags  in the \fBc_iflag\fR field other than the \fBIXOFF\fR and
\fBIXANY\fR flags  are cleared  in the \fBtermios\fR structure).  Eight bits of
data, with no parity bit are accepted on input and generated on output; the
character size is set to \fBCS8\fR and the \fBPARENB\fR and \fBPARODD\fR flags
are cleared in the \fBc_cflag\fR field of the \fBtermios\fR structure. The
signal-generating and line-editing control characters are disabled by clearing
the \fBISIG\fR and \fBICANON\fR flags in the \fBc_iflag\fR field of the termios
structure.
.sp
.LP
The \fBCRMOD\fR flag turns input carriage return characters into linefeed
characters, and output linefeed characters to be sent as a carriage return
followed by a linefeed. The \fBICRNL\fR flag in the \fBc_iflag\fR field, and
the \fBOPOST\fR and \fBONLCR\fR flags in the \fBc_oflag field\fR, are set in
the termios structure.
.sp
.LP
The \fBLCASE\fR flag maps upper-case letters in the \fBASCII\fR character set
to their lower-case equivalents on input (the \fBIUCLC\fR flag is set in the
\fBc_iflag\fR field), and maps lower-case letters in the \fBASCII\fR character
set to their upper-case equivalents on output (the \fBOLCUC\fR flag is set in
the \fBc_oflag\fR field). Escape sequences are accepted on input, and generated
on output, to handle certain \fBASCII\fR characters not supported by older
terminals (the \fBXCASE\fR flag is set in the \fBc_lflag\fR field).
.sp
.LP
Other flags are directly mapped to flags in the \fBtermios\fR structure:
.sp

.sp
.TS
tab() box;
cw(0i) |cw(5.5i) 
lw(0i) |lw(5.5i) 
.
sg_flagsFlags in termios structure
_
CBREAKComplement of ICANON in c_lflag field
_
ECHOECHO in c_lflag field
_
TANDEMIXOFF in c_iflag field
.TE

.sp
.LP
Another structure associated with each terminal specifies characters that are
special in both the old Version 7 and the newer \fB4BSD\fR terminal interfaces.
The following structure is defined by \fB<sys/ttold.h>\fR:
.sp
.in +2
.nf
struct   tchars   {
          char t_intrc;     /* interrupt */
          char t_quitc;     /* quit */
          char t_startc; /* start output */
          char t_stopc;     /* stop output */
          char t_eofc;        /* end-of-file */
          char t_brkc;        /* input delimiter (like nl) */
     };
.fi
.in -2

.sp
.LP
\fBXENIX\fR defines the  \fBtchar\fR structure as  \fBtc\fR. The characters are
mapped to members of the \fBc_cc\fR field of the \fBtermios\fR structure as
follows:
.sp
.in +2
.nf
       tchars                c_cc index
       t_intrc               VINTR
       t_quitc               VQUIT
       t_startc              VSTART
       t_stopc               VSTOP
       t_eofc                VEOF
       t_brkc                VEOL
.fi
.in -2

.sp
.LP
Also associated with each terminal is a local flag word (\fBTIOCLSET\fR and
\fBTIOCLGET\fR), specifying flags  supported by the new 4BSD terminal
interface. Most of these flags are directly mapped to flags in the
\fBtermios\fR structure:
.sp

.sp
.TS
tab() box;
cw(0i) |cw(5.5i) 
lw(0i) |lw(5.5i) 
.
Local flagsFlags in termios structure
_
LCRTBSNot supported 
_
LPRTERAECHOPRT in the c_lflag field
_
LCRTERAECHOE in the c_lflag field
_
LTILDENot supported
_
LMDMBUFNot supported
_
LTOSTOPTOSTOP in the c_lflag field
_
LFLUSHOFLUSHO in the c_lflag field
_
LNOHANGCLOCAL in the c_cflag field
_
LCRTKILECHOKE in the c_lflag field
_
LPASS8CS8 in the c_cflag field
_
LCTLECHCTLECH in the c_lflag field 
_
LPENDINPENDIN in the c_lflag field
_
LDECCTQComplement of IXANY in the c_iflag field
_
LNOFLSHNOFLSH in the c_lflag field
.TE

.sp
.LP
Each flag has a corresponding equivalent \fBsg_flags\fR value. The
\fBsg_flags\fR definitions omit the leading "L"; for example, TIOCSETP with
\fBsg_flags\fR set to TOSTOP is equivalent to TIOCLSET with LTOSTOP.
.sp
.LP
Another structure associated with each terminal is the \fBltchars\fR structure
which defines control characters for the new \fB4BSD\fR terminal interface. Its
structure is:
.sp
.in +2
.nf
struct ltchars {
   char t_suspc;  /* stop process signal */
   char t_dsuspc; /* delayed stop process signal */
   char t_rprntc; /* reprint line */
   char t_flushc; /*flush output (toggles) */
   char t_werasc; /* word erase */
   char t_lnextc; /* literal next character */
};
.fi
.in -2

.sp
.LP
The characters are mapped to members of the \fBc_cc\fR field of the
\fBtermios\fR structure as follows:
.sp

.sp
.TS
tab() box;
cw(0i) |cw(5.5i) 
lw(0i) |lw(5.5i) 
.
ltcharsc_cc index
_
t_suspc VSUS 
_
t_dsuspcVDSUSP
_
t_rprntcVREPRINT
_
t_flushcVDISCARD
_
t_werascVWERASE
_
t_lnextcVLNEXT
.TE

.SH IOCTLS
.sp
.LP
\fBttcompat\fR responds to the following \fBioctl\fR calls. All others are
passed to the module below.
.sp
.ne 2
.mk
.na
\fB\fBTIOCGETP\fR \fR
.ad
.RS 14n
.rt  
The argument is a pointer to an \fBsgttyb\fR structure. The current  terminal
state is fetched; the  appropriate characters in  the terminal  state are
stored  in that structure, as are the input and output speeds. If the speed is
over B38400,  then B38400 is  returned. The values of the flags in the
\fBsg_flags\fR field are derived from the flags in the terminal state and
stored in the structure.
.RE

.sp
.ne 2
.mk
.na
\fB\fBTIOCEXCL\fR \fR
.ad
.RS 14n
.rt  
Set ``exclusive-use'' mode; no further opens are  permitted until the file has
been closed.
.RE

.sp
.ne 2
.mk
.na
\fB\fBTIOCNXCL\fR \fR
.ad
.RS 14n
.rt  
Turn off ``exclusive-use'' mode.
.RE

.sp
.ne 2
.mk
.na
\fB\fBTIOCSETP\fR \fR
.ad
.RS 14n
.rt  
The argument is a pointer to an \fBsgttyb\fR structure. The appropriate
characters and input and output speeds in the terminal state are set from the
values in that structure, and the flags in the terminal state are set to match
the values of the flags in the \fBsg_flags\fR field of that structure. The
state is changed with a \fBTCSETSF\fR \fBioctl\fR so that the interface delays
until output is quiescent, then throws away any unread characters, before
changing the modes. If the current device speed is over B38400 for either input
or output speed, and B38400 is specified through this interface for that speed,
the actual device speed is not changed. If the device speed is B38400 or lower
or if some speed other than B38400 is specified, then the actual speed
specified is set.
.RE

.sp
.ne 2
.mk
.na
\fB\fBTIOCSETN\fR \fR
.ad
.RS 14n
.rt  
The argument is a pointer to an \fBsgttyb\fR structure. The terminal state is
changed as  \fBTIOCSETP\fR would change it, but a \fBTCSETS\fR \fBioctl\fR is
used, so that the interface neither delays nor discards input.
.RE

.sp
.ne 2
.mk
.na
\fB\fBTIOCHPCL\fR \fR
.ad
.RS 14n
.rt  
The argument is ignored. The \fBHUPCL\fR flag is set in the \fBc_cflag\fR word
of the terminal state.
.RE

.sp
.ne 2
.mk
.na
\fB\fBTIOCFLUSH\fR \fR
.ad
.RS 14n
.rt  
The argument is a pointer to an \fBint\fR variable. If its value is zero, all
characters waiting in input or output queues are flushed. Otherwise, the value
of the \fBint\fR is treated as the logical \fBOR\fR of the \fBFREAD\fR and
\fBFWRITE\fR flags defined by \fB<sys/file.h>\fR\&. If the \fBFREAD\fR bit is
set, all characters waiting in input queues are flushed, and if the
\fBFWRITE\fR bit is set, all characters waiting in output queues are flushed.
.RE

.sp
.ne 2
.mk
.na
\fB\fBTIOCSBRK\fR \fR
.ad
.RS 14n
.rt  
The argument is ignored. The break bit is set for the device. (This  is not
supported  by \fBttcompat\fR. The underlying driver must support TIOCSBRK.)
.RE

.sp
.ne 2
.mk
.na
\fB\fBTIOCCBRK\fR \fR
.ad
.RS 14n
.rt  
The argument is ignored. The break bit is cleared for the device. (This is not
supported by \fBttcompat\fR. The underlying driver must support TIOCCBRK.)
.RE

.sp
.ne 2
.mk
.na
\fB\fBTIOCSDTR\fR \fR
.ad
.RS 14n
.rt  
The argument is ignored. The Data Terminal Ready bit is set for the device.
.RE

.sp
.ne 2
.mk
.na
\fB\fBTIOCCDTR\fR \fR
.ad
.RS 14n
.rt  
The argument is ignored. The Data Terminal Ready bit is cleared for the device.
.RE

.sp
.ne 2
.mk
.na
\fB\fBTIOCSTOP\fR \fR
.ad
.RS 14n
.rt  
The argument is ignored. Output is stopped as if the \fBSTOP\fR character had
been typed.
.RE

.sp
.ne 2
.mk
.na
\fB\fBTIOCSTART\fR \fR
.ad
.RS 14n
.rt  
The argument is ignored. Output is restarted as if the \fBSTART\fR character
had been typed.
.RE

.sp
.ne 2
.mk
.na
\fB\fBTIOCGETC\fR \fR
.ad
.RS 14n
.rt  
The argument is a pointer to a \fBtchars\fR structure. The current terminal
state is fetched, and the appropriate characters in the terminal state are
stored in that structure.
.RE

.sp
.ne 2
.mk
.na
\fB\fBTIOCSETC\fR \fR
.ad
.RS 14n
.rt  
The argument is a pointer to a \fBtchars\fR structure. The values of the
appropriate characters in the terminal state are set from the characters in
that structure.
.RE

.sp
.ne 2
.mk
.na
\fB\fBTIOCLGET\fR \fR
.ad
.RS 14n
.rt  
The argument is a pointer to an \fBint\fR. The current terminal state is
fetched, and the values of the local flags are derived from the flags in the
terminal state and stored in the \fBint\fR pointed to by the argument.
.RE

.sp
.ne 2
.mk
.na
\fB\fBTIOCLBIS\fR \fR
.ad
.RS 14n
.rt  
The argument is a pointer to an \fBint\fR whose value is a mask containing
flags to be set in the local flags word. The current terminal state is fetched,
and the values of the local flags are derived from the flags in the terminal
state; the specified flags are set, and the flags in the terminal state are set
to match the new value of the local flags word.
.RE

.sp
.ne 2
.mk
.na
\fB\fBTIOCLBIC\fR \fR
.ad
.RS 14n
.rt  
The argument is a pointer to an \fBint\fR whose value is a mask containing
flags to be cleared in the local flags word. The current terminal state is
fetched, and the values of the local flags are derived from the flags in the
terminal state; the specified flags are cleared, and the flags in the terminal
state are set to match the new value of the local flags word.
.RE

.sp
.ne 2
.mk
.na
\fB\fBTIOCLSET\fR \fR
.ad
.RS 14n
.rt  
The argument is a pointer to an int containing a new set of local flags. The
flags in the terminal state are set to match the  new value of the local flags
word.  (This \fBioctl\fR was added because \fBsg_flags\fR was once a 16  bit
value. The local modes controlled by TIOCLSET are equivalent to the modes
controlled by TIOCSETP and \fBsg_flags\fR.)
.RE

.sp
.ne 2
.mk
.na
\fB\fBTIOCGLTC\fR \fR
.ad
.RS 14n
.rt  
The argument is a pointer to an \fBltchars\fR structure. The values of the
appropriate characters in the terminal state are stored in that structure.
.RE

.sp
.ne 2
.mk
.na
\fB\fBTIOCSLTC\fR \fR
.ad
.RS 14n
.rt  
The argument is a pointer to an \fBltchars\fR structure. The values of the
appropriate characters in the terminal state are set from the characters in
that structure.
.RE

.sp
.ne 2
.mk
.na
\fB\fBFIORDCHK\fR \fR
.ad
.RS 14n
.rt  
Returns the number of immediately readable characters. The argument is ignored.
(This ioctl is  handled in the stream head, not in the \fBttcompat\fR module.)
.RE

.sp
.ne 2
.mk
.na
\fB\fBFIONREAD\fR \fR
.ad
.RS 14n
.rt  
Returns the number of immediately readable characters in the int pointed to by
the argument. (This ioctl is  handled in the stream head, not in the
\fBttcompat\fR module.)
.RE

.sp
.LP
The following ioctls are returned as successful for the sake of compatibility.
However, nothing significant is done (that is, the state of the terminal is not
changed in any way, and no message is passed through to the underlying
\fBtty\fR driver).
.sp
.in +2
.nf
         
DIOCSETP
DIOCSETP
DIOCGETP
LDCLOSE  
LDCHG
LDOPEN
LDGETT
LDSETT
TIOCGETD
TIOCSETD
.fi
.in -2

.sp
.LP
The following old \fBioctl\fRs are not supported by \fBttcompat\fR, but are
supported by Solaris \fBtty\fR drivers. As with all ioctl not otherwise listed
in this documentation, these are passed through to the underlying driver and
are handled there.
.sp
.in +2
.nf
TIOCREMOTE
TIOCGWINSZ 
TIOCSWINSZ
.fi
.in -2

.sp
.LP
The following \fBioctls\fR are  not supported by \fBttcompat\fR, and are
generally not supported by Solaris \fBtty\fR drivers. They are  passed through,
and the \fBtty\fR drivers return EINVAL.
.sp
.in +2
.nf
LDSMAP
LDGMAP 
LDNMAP
TIOCNOTTY
TIOCOUTQ
.fi
.in -2

.sp
.LP
(Note:   LDSMAP,   LDGMAP,  and   LDNMAP   are  defined   in
<\fBsys/termios.h\fR>.)
.SH SEE ALSO
.sp
.LP
\fBioctl\fR(2), \fBtermios\fR(3C), \fBldterm\fR(7M), \fBtermio\fR(7I)