1.\" Copyright 1989 AT&T 2.\" Copyright (C) 1999, Sun Microsystems, Inc. All Rights Reserved 3.\" Copyright (c) 2017, Joyent, Inc. 4.\" The contents of this file are subject to the terms of the 5.\" Common Development and Distribution License (the "License"). 6.\" You may not use this file except in compliance with the License. 7.\" 8.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9.\" or http://www.opensolaris.org/os/licensing. 10.\" See the License for the specific language governing permissions 11.\" and limitations under the License. 12.\" 13.\" When distributing Covered Code, include this CDDL HEADER in each 14.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15.\" If applicable, add the following below this CDDL HEADER, with the 16.\" fields enclosed by brackets "[]" replaced with your own identifying 17.\" information: Portions Copyright [yyyy] [name of copyright owner] 18.Dd October 29, 2017 19.Dt TERMIOX 4I 20.Os 21.Sh NAME 22.Nm termiox 23.Nd extended general terminal interface 24.Sh DESCRIPTION 25The extended general terminal interface supplements the 26.Xr termio 4I 27general terminal interface by adding support for asynchronous hardware flow 28control, isochronous flow control and clock modes, and local implementations of 29additional asynchronous features. 30Some systems may not support all of these 31capabilities because of either hardware or software limitations. 32Other systems may not permit certain functions to be disabled. 33In these cases the appropriate bits will be ignored. 34See 35.In sys/termiox.h 36for your system to find out which capabilities are supported. 37.Ss "Hardware Flow Control Modes" 38Hardware flow control supplements the 39.Xr termio 4I 40.Dv IXON , 41.Dv IXOFF , 42and 43.Dv IXANY 44character flow control. 45Character flow control occurs when one 46device controls the data transfer of another device by the insertion of control 47characters in the data stream between devices. 48Hardware flow control occurs 49when one device controls the data transfer of another device using electrical 50control signals on wires (circuits) of the asynchronous interface. 51Isochronous 52hardware flow control occurs when one device controls the data transfer of 53another device by asserting or removing the transmit clock signals of that 54device. 55Character flow control and hardware flow control may be simultaneously 56set. 57.Pp 58In asynchronous, full duplex applications, the use of the Electronic Industries 59Association's EIA-232-D Request To Send (RTS) and Clear To Send (CTS) circuits 60is the preferred method of hardware flow control. 61An interface to other 62hardware flow control methods is included to provide a standard interface to 63these existing methods. 64.Pp 65The EIA-232-D standard specified only unidirectional hardware flow control \(em 66the Data Circuit-terminating Equipment or Data Communications Equipment (DCE) 67indicates to the Data Terminal Equipment (DTE) to stop transmitting data. 68The 69.Nm 70interface allows both unidirectional and bidirectional hardware 71flow control; when bidirectional flow control is enabled, either the DCE or DTE 72can indicate to each other to stop transmitting data across the interface. 73Note: It is assumed that the asynchronous port is configured as a DTE. 74If the 75connected device is also a DTE and not a DCE, then DTE to DTE (for example, 76terminal or printer connected to computer) hardware flow control is possible by 77using a null modem to interconnect the appropriate data and control circuits. 78.Ss "Clock Modes" 79Isochronous communication is a variation of asynchronous communication whereby 80two communicating devices may provide transmit and/or receive clock signals to 81one another. 82Incoming clock signals can be taken from the baud rate generator 83on the local isochronous port controller, from CCITT V\.24 circuit 114, 84Transmitter Signal Element Timing - DCE source (EIA-232-D pin 15), or from 85CITT V\.24 circuit 115, Receiver Signal Element Timing - DCE source (EIA-232-D 86pin 17). 87Outgoing clock signals can be sent on CCITT V\.24 circuit 113, 88Transmitter Signal Element Timing - DTE source (EIA-232-D pin 24), on CCITT 89V\.24 circuit 128, Receiver Signal Element Timing - DTE source (no EIA-232-D 90pin), or not sent at all. 91.Pp 92In terms of clock modes, traditional asynchronous communication is implemented 93simply by using the local baud rate generator as the incoming transmit and 94receive clock source and not outputting any clock signals. 95.Ss "Terminal Parameters" 96The parameters that control the behavior of devices providing the 97.Nm 98interface are specified by the 99.Vt termiox 100structure defined in the 101.In sys/termiox.h 102header. 103Several 104.Xr ioctl 2 105system calls that fetch 106or change these parameters use this structure: 107.Bd -literal -offset 2n 108#define NFF 5 109struct termiox { 110 unsigned short x_hflag; /* hardware flow control modes */ 111 unsigned short x_cflag; /* clock modes */ 112 unsigned short x_rflag[NFF]; /* reserved modes */ 113 unsigned short x_sflag; /* spare local modes */ 114}; 115.Ed 116.Pp 117The 118.Fa x_hflag 119field describes hardware flow control modes: 120.Bl -column xxxxxxx xxxxxxx x 121.It Dv RTSXOFF Ta 0000001 Ta "Enable RTS hardware flow control on input." 122.It Dv CTSXON Ta 0000002 Ta "Enable CTS hardware flow control on output." 123.It Dv DTRXOFF Ta 0000004 Ta "Enable DTR hardware flow control on input." 124.It Dv CDXON Ta 0000010 Ta "Enable CD hardware flow control on output." 125.It Dv ISXOFF Ta 0000020 Ta "Enable isochronous hardware flow control on input." 126.El 127.Pp 128The EIA-232-D DTR and CD circuits are used to establish a connection between 129two systems. 130The RTS circuit is also used to establish a connection with a modem. 131Thus, both DTR and RTS are activated when an asynchronous port is opened. 132If DTR is used for hardware flow control, then RTS must be used for 133connectivity. 134If CD is used for hardware flow control, then CTS must be used 135for connectivity. 136Thus, RTS and DTR (or CTS and CD) cannot both be used for 137hardware flow control at the same time. 138Other mutual exclusions may apply, such as the simultaneous setting of the 139.Xr termio 4I 140.Dv HUPCL 141and the 142.Vt termiox 143.Dv DTRXOFF 144bits, which use the DTE ready line for different functions. 145.Pp 146Variations of different hardware flow control methods may be selected by 147setting the appropriate bits. 148For example, bidirectional RTS/CTS flow control is selected by setting both the 149.Dv RTSXOFF 150and 151.Dv CTSXON 152bits and bidirectional DTR/CTS flow control is selected by setting both the 153.Dv DTRXOFF 154and 155.Dv CTSXON . 156Modem control or unidirectional CTS hardware 157flow control is selected by setting only the 158.Dv CTSXON 159bit. 160.Pp 161As previously mentioned, it is assumed that the local asynchronous port (for 162example, computer) is configured as a DTE. 163If the connected device (for example, printer) is also a DTE, it is assumed 164that the device is connected to the computer's asynchronous port using a null 165modem that swaps control circuits (typically RTS and CTS). 166The connected DTE drives RTS and the null modem swaps 167RTS and CTS so that the remote RTS is received as CTS by the local DTE. 168In the case that 169.Dv CTSXON 170is set for hardware flow control, printer's lowering 171of its RTS would cause CTS seen by the computer to be lowered. 172Output to the printer is suspended until the printer's raising of its RTS, 173which would cause CTS seen by the computer to be raised. 174.Pp 175If 176.Dv RTSXOFF 177is set, the Request To Send (RTS) circuit (line) will be 178raised, and if the asynchronous port needs to have its input stopped, it will 179lower the Request To Send (RTS) line. 180If the RTS line is lowered, it is assumed 181that the connected device will stop its output until RTS is raised. 182.Pp 183If 184.Dv CTSXON 185is set, output will occur only if the Clear To Send (CTS) 186circuit (line) is raised by the connected device. 187If the CTS line is lowered by 188the connected device, output is suspended until CTS is raised. 189.Pp 190If 191.Dv DTRXOFF 192is set, the DTE Ready (DTR) circuit (line) will be raised, and 193if the asynchronous port needs to have its input stopped, it will lower the DTE 194Ready (DTR) line. 195If the DTR line is lowered, it is assumed that the connected 196device will stop its output until DTR is raised. 197.Pp 198If 199.Dv CDXON 200is set, output will occur only if the Received Line Signal 201Detector (CD) circuit (line) is raised by the connected device. 202If the CD line 203is lowered by the connected device, output is suspended until CD is raised. 204.Pp 205If 206.Dv ISXOFF 207is set, and if the isochronous port needs to have its input 208stopped, it will stop the outgoing clock signal. 209It is assumed that the 210connected device is using this clock signal to create its output. 211Transit and receive clock sources are programmed using the 212.Fa x_cflag 213fields. 214If the port is not programmed for external clock generation, 215.Dv ISXOFF 216is ignored. 217Output isochronous flow control is supported by appropriate clock source 218programming using the 219.Fa x_cflag 220field and enabled at the remote connected device. 221.Pp 222The 223.Fa x_cflag 224field specifies the system treatment of clock modes. 225.Bl -column xxxxxxxxx xxxxxxxx l 226.It Dv XMTCLK Ta 0000007 Ta "Transmit clock source:" 227.It Dv XCIBRG Ta 0000000 Ta "Get transmit clock from internal baud rate generator." 228.It Dv XCTSET Ta 0000001 Ta "Get transmit clock from transmitter signal element timing (DCE source) lead, CCITT V\.24 circuit 114, EIA-232-D pin 15." 229.It Dv XCRSET Ta 0000002 Ta Get transmit clock from receiver signal element timing (DCE source) lead, CCITT V\.4 circuit 115, EIA-232-D pin 17." 230.It Dv RCVCLK Ta 0000070 Ta "Receive clock source:" 231.It Dv RCIBRG Ta 0000000 Ta "Get receive clock from internal baud rate generator." 232.It Dv RCTSET Ta 0000010 Ta "Get receive clock from transmitter signal element timing (DCE source) lead, CCITT V\.24 circuit 114, EIA-232-D pin 15." 233.It Dv RCRSET Ta 0000020 Ta "Get receive clock from receiver signal element timing (DCE source) lead, CCITT V\.24 circuit 115, EIA-232-D pin 17." 234.It Dv TSETCLK Ta 0000700 Ta "Transmitter signal element timing (DTE source) lead, CCITT V\.24 circuit 113, EIA-232-D pin 24, clock source:" 235.It Dv TSETCOFF Ta 0000000 Ta "TSET clock not provided." 236.It Dv TSETCRBRG Ta 0000100 Ta "Output receive baud rate generator on circuit 113." 237.It Dv TSETCTBRG Ta 0000200 Ta "Output transmit baud rate generator on circuit 113" 238.It Dv TSETCTSET Ta 0000300 Ta "Output transmitter signal element timing (DCE source) on circuit 113." 239.It Dv TSETCRSET Ta 0000400 Ta "Output receiver signal element timing (DCE source) on circuit 113." 240.It Dv RSETCLK Ta 0007000 Ta "Receiver signal element timing (DTE source) lead, CCITT V\.24 circuit 128, no EIA-232-D pin, clock source:" 241.It Dv RSETCOFF Ta 0000000 Ta "RSET clock not provided." 242.It Dv RSETCRBRG Ta 0001000 Ta "Output receive baud rate generator on circuit 128." 243.It Dv RSETCTBRG Ta 0002000 Ta "Output transmit baud rate generator on circuit 128." 244.It Dv RSETCTSET Ta 0003000 Ta "Output transmitter signal element timing (DCE source) on circuit 128." 245.It Dv RSETCRSET Ta 0004000 Ta "Output receiver signal element timing (DCE) on circuit 128." 246.El 247.Pp 248If the 249.Fa XMTCLK 250field has a value of 251.Dv XCIBRG 252the transmit clock is taken from the hardware internal baud rate generator, as 253in normal asynchronous transmission. 254If 255.Fa XMTCLK 256= 257.Dv XCTSET 258the transmit clock is taken from 259the Transmitter Signal Element Timing (DCE source) circuit. 260If 261.Fa XMTCLK 262= 263.Dv XCRSET 264the transmit clock is taken from the Receiver Signal Element 265Timing (DCE source) circuit. 266.Pp 267If the 268.Fa RCVCLK 269field has a value of 270.Dv RCIBRG , 271the receive clock is 272taken from the hardware Internal Baud Rate Generator, as in normal asynchronous 273transmission. 274If 275.Fa RCVCLK 276= 277.Dv RCTSET 278the receive clock is taken from 279the Transmitter Signal Element Timing (DCE source) circuit. 280If 281.Fa RCVCLK 282= 283.Dv RCRSET 284the receive clock is taken from the Receiver Signal Element Timing 285(DCE source) circuit. 286.Pp 287If the 288.Fa TSETCLK 289field has a value of 290.Dv TSETCOFF 291the Transmitter Signal Element Timing (DTE source) circuit is not driven. 292If 293.Fa TSETCLK 294= 295.Dv TSETCRBRG 296the Transmitter Signal Element Timing (DTE source) circuit is 297driven by the Receive Baud Rate Generator. 298If 299.Fa TSETCLK 300= 301.Dv TSETCTBRG 302the Transmitter Signal Element Timing (DTE source) circuit is driven by the 303Transmit Baud Rate Generator. 304If 305.Fa TSETCLK 306= 307.Dv TSETCTSET 308the Transmitter Signal Element Timing (DTE source) circuit is driven by the 309Transmitter Signal Element Timing (DCE source). 310If 311.Fa TSETCLK 312= 313.Dv TSETCRBRG 314the Transmitter Signal Element Timing (DTE source) circuit is 315driven by the Receiver Signal Element Timing (DCE source). 316.Pp 317If the 318.Fa RSETCLK 319field has a value of 320.Dv RSETCOFF 321the Receiver Signal Element Timing (DTE source) circuit is not driven. 322If 323.Fa RSETCLK 324= 325.Dv RSETCRBRG 326the Receiver Signal Element Timing (DTE source) circuit is 327driven by the Receive Baud Rate Generator. 328If 329.Fa RSETCLK 330= 331.Dv RSETCTBRG 332the Receiver Signal Element Timing (DTE source) circuit is driven by the 333Transmit Baud Rate Generator. 334If 335.Fa RSETCLK 336= 337.Dv RSETCTSET 338the Receiver 339Signal Element Timing (DTE source) circuit is driven by the Transmitter Signal 340Element Timing (DCE source). 341If 342.Fa RSETCLK 343= 344.Dv RSETCRBRG 345the Receiver 346Signal Element Timing (DTE source) circuit is driven by the Receiver Signal 347Element Timing (DCE source). 348.Pp 349The 350.Fa x_rflag 351is reserved for future interface definitions and should not 352be used by any implementations. 353The 354.Fa x_sflag 355may be used by local 356implementations wishing to customize their terminal interface using the 357.Nm 358ioctl system calls. 359.Sh IOCTLS 360The 361.Xr ioctl 2 362system calls have the form: 363.Bd -literal -offset 2n 364struct termiox *arg; 365ioctl(fildes, command, arg); 366.Ed 367.Pp 368The commands using this form are: 369.Bl -tag -width TCSETXW 370.It Dv TCGETX 371The argument is a pointer to a 372.Vt termiox 373structure. 374The current terminal parameters are fetched and stored into that structure. 375.It Dv TCSETX 376The argument is a pointer to a 377.Vt termiox 378structure. 379The current terminal parameters are set from the values stored in that structure. 380The change is immediate. 381.It Dv TCSETXW 382The argument is a pointer to a 383.Vt termiox 384structure. 385The current terminal parameters are set from the values stored in that structure. 386The change occurs after all characters queued for output have been transmitted. 387This form should be used when changing parameters that will affect output. 388.It Dv TCSETXF 389The argument is a pointer to a 390.Vt termiox 391structure. 392The current terminal parameters are set from the values stored in that structure. 393The change occurs 394after all characters queued for output have been transmitted; all characters 395queued for input are discarded and then the change occurs. 396.El 397.Sh FILES 398.Pa /dev/* 399.Sh SEE ALSO 400.Xr stty 1 , 401.Xr ioctl 2 , 402.Xr termio 4I 403.Sh NOTES 404The 405.Nm termiox Ns Pq 4I 406system call is provided for compatibility with previous 407releases and its use is discouraged. 408Instead, the 409.Xr termio 4I 410system call is recommended. 411See 412.Xr termio 4I 413for usage information. 414