path: root/usr/src/man/man4m/ttcompat.4m

'\" 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 4M "Oct 2, 2001"
.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(4I)). 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
box;
c | c
l | l .
sg_flags	c_oflag
_
BS1	BS1
_
FF1	VT1
_
CR1	CR2
_
CR2	CR3
_
CR3	CR0 (not supported)
_
TAB1	TAB1
_
TAB2	TAB2
_
XTABS	TAB3
_
NL1	ONLRET|CR1
_
NL2	NL1
_
NL3	NL0 (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
.na
\fB0 (neither EVENP nor ODDP)\fR
.ad
.RS 30n
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
.na
\fBEVENP\fR
.ad
.RS 30n
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
.na
\fBODDP\fR
.ad
.RS 30n
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
.na
\fBEVENP|ODDP or ANYP\fR
.ad
.RS 30n
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
box;
c | c
l | l .
sg_flags	Flags in termios structure
_
CBREAK	Complement of ICANON in c_lflag field
_
ECHO	ECHO in c_lflag field
_
TANDEM	IXOFF 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
box;
c | c
l | l .
Local flags	Flags in termios structure
_
LCRTBS	Not supported
_
LPRTERA	ECHOPRT in the c_lflag field
_
LCRTERA	ECHOE in the c_lflag field
_
LTILDE	Not supported
_
LMDMBUF	Not supported
_
LTOSTOP	TOSTOP in the c_lflag field
_
LFLUSHO	FLUSHO in the c_lflag field
_
LNOHANG	CLOCAL in the c_cflag field
_
LCRTKIL	ECHOKE in the c_lflag field
_
LPASS8	CS8 in the c_cflag field
_
LCTLECH	CTLECH in the c_lflag field
_
LPENDIN	PENDIN in the c_lflag field
_
LDECCTQ	Complement of IXANY in the c_iflag field
_
LNOFLSH	NOFLSH 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
box;
c | c
l | l .
ltchars	c_cc index
_
t_suspc 	VSUS
_
t_dsuspc	VDSUSP
_
t_rprntc	VREPRINT
_
t_flushc	VDISCARD
_
t_werasc	VWERASE
_
t_lnextc	VLNEXT
.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
.na
\fB\fBTIOCGETP\fR \fR
.ad
.RS 14n
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
.na
\fB\fBTIOCEXCL\fR \fR
.ad
.RS 14n
Set ``exclusive-use'' mode; no further opens are  permitted until the file has
been closed.
.RE

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

.sp
.ne 2
.na
\fB\fBTIOCSETP\fR \fR
.ad
.RS 14n
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
.na
\fB\fBTIOCSETN\fR \fR
.ad
.RS 14n
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
.na
\fB\fBTIOCHPCL\fR \fR
.ad
.RS 14n
The argument is ignored. The \fBHUPCL\fR flag is set in the \fBc_cflag\fR word
of the terminal state.
.RE

.sp
.ne 2
.na
\fB\fBTIOCFLUSH\fR \fR
.ad
.RS 14n
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
.na
\fB\fBTIOCSBRK\fR \fR
.ad
.RS 14n
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
.na
\fB\fBTIOCCBRK\fR \fR
.ad
.RS 14n
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
.na
\fB\fBTIOCSDTR\fR \fR
.ad
.RS 14n
The argument is ignored. The Data Terminal Ready bit is set for the device.
.RE

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

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

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

.sp
.ne 2
.na
\fB\fBTIOCGETC\fR \fR
.ad
.RS 14n
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
.na
\fB\fBTIOCSETC\fR \fR
.ad
.RS 14n
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
.na
\fB\fBTIOCLGET\fR \fR
.ad
.RS 14n
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
.na
\fB\fBTIOCLBIS\fR \fR
.ad
.RS 14n
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
.na
\fB\fBTIOCLBIC\fR \fR
.ad
.RS 14n
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
.na
\fB\fBTIOCLSET\fR \fR
.ad
.RS 14n
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
.na
\fB\fBTIOCGLTC\fR \fR
.ad
.RS 14n
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
.na
\fB\fBTIOCSLTC\fR \fR
.ad
.RS 14n
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
.na
\fB\fBFIORDCHK\fR \fR
.ad
.RS 14n
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
.na
\fB\fBFIONREAD\fR \fR
.ad
.RS 14n
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
.BR ioctl (2),
.BR termios (3C),
.BR termio (4I),
.BR ldterm (4M)